docs/LAION_DATASET_GUIDE.md

# LAION数据集下载指南

## 问题描述

运行代码时出现以下错误：
```
FileNotFoundError: [Errno 2] No such file or directory: './data/laion/metadata.parquet'
```

这是因为项目需要LAION数据集，但数据集文件不存在。

## LAION数据集简介

LAION（Large-scale Artificial Intelligence Open Network）是一个大规模的多模态数据集，包含：
- **LAION-5B**: 58.5亿个图像-文本对
- **LAION-Aesthetic**: 经过美学评分筛选的高质量子集
- **LAION-400M**: 4亿个图像-文本对

## 解决方案

### 方案1：使用虚拟数据集测试（推荐）

对于测试和开发，可以使用虚拟数据集：

```bash
# 创建虚拟数据集
python scripts/download_laion.py --dummy --dummy-size 100

# 或者直接运行
python scripts/download_laion.py --dummy
```

这将创建一个包含100条虚拟记录的元数据文件，用于测试代码流程。

### 方案2：下载LAION-Aesthetic子集

LAION-Aesthetic是经过美学评分筛选的高质量数据集：

```bash
# 下载LAION-Aesthetic 6.5+子集（默认）
python scripts/download_laion.py

# 下载LAION-Aesthetic 7.0+子集（更高质量）
python scripts/download_laion.py --subset "7.0+"
```

### 方案3：下载LAION-5B样本

```bash
# 下载10,000条记录的样本
python scripts/download_laion.py --sample-size 10000
```

## 手动下载方法

### 方法1：从Hugging Face下载

1. **访问Hugging Face数据集页面**：
   - LAION-Aesthetic 6.5+: https://huggingface.co/datasets/laion/laion-aesthetic-6.5plus
   - LAION-Aesthetic 7.0+: https://huggingface.co/datasets/laion/laion-aesthetic-7.0plus
   - LAION-5B: https://huggingface.co/datasets/laion/laion2b-en

2. **下载元数据文件**：
   ```bash
   # 创建目录
   mkdir -p data/laion
   
   # 下载LAION-Aesthetic 6.5+元数据
   wget https://huggingface.co/datasets/laion/laion-aesthetic-6.5plus/resolve/main/data/00000.parquet -O data/laion/metadata.parquet
   
   # 或者使用curl
   curl -L https://huggingface.co/datasets/laion/laion-aesthetic-6.5plus/resolve/main/data/00000.parquet -o data/laion/metadata.parquet
   ```

### 方法2：使用img2dataset工具

`img2dataset`是一个专门用于下载LAION数据集的工具：

```bash
# 安装img2dataset
pip install img2dataset

# 下载LAION-400M子集
img2dataset \
  --url_list "path/to/laion-400m.parquet" \
  --input_format "parquet" \
  --url_col "URL" \
  --caption_col "TEXT" \
  --output_folder "data/laion/images" \
  --processes_count 16 \
  --thread_count 64 \
  --image_size 512 \
  --resize_mode "keep_ratio" \
  --output_format "webdataset"
```

### 方法3：使用官方脚本

LAION官方提供了一些下载脚本：

```bash
# 克隆LAION工具仓库
git clone https://github.com/rom1504/img2dataset.git
cd img2dataset

# 查看使用说明
python -m img2dataset --help
```

## 数据集结构

下载后，数据集目录结构应为：

```
data/
└── laion/
    ├── metadata.parquet          # 元数据文件（必需）
    ├── dataset_info.json         # 数据集信息文件
    └── images/                   # 图像文件目录（可选）
        ├── 00000.tar
        ├── 00001.tar
        └── ...
```

### 元数据文件格式

`metadata.parquet`文件通常包含以下列：
- `url`: 图像URL
- `caption` 或 `text`: 图像描述文本
- `aesthetic_score`: 美学评分（LAION-Aesthetic特有）
- `watermark_prob`: 水印概率
- `NSFW`: 成人内容标记
- `width`/`height`: 图像尺寸

## 验证数据集

下载完成后，验证数据集是否正确：

```python
import pandas as pd
import os

# 检查文件是否存在
metadata_path = "./data/laion/metadata.parquet"
if os.path.exists(metadata_path):
    print(f"元数据文件存在: {metadata_path}")
    
    # 读取前几行
    df = pd.read_parquet(metadata_path)
    print(f"记录数: {len(df)}")
    print(f"列名: {list(df.columns)}")
    print("\n前5条记录:")
    print(df.head())
else:
    print(f"错误: 文件不存在 {metadata_path}")
```

## 常见问题

### 问题1：下载速度慢
- **解决方案**：使用国内镜像或代理
- 可以尝试使用清华镜像：`pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple`

### 问题2：存储空间不足
- **解决方案**：
  1. 下载较小的子集（如LAION-Aesthetic）
  2. 使用虚拟数据集进行测试
  3. 只下载元数据，不下载图像

### 问题3：网络连接问题
- **解决方案**：
  1. 使用`--dummy`参数创建虚拟数据集
  2. 手动下载小样本文件
  3. 使用现有的本地数据集

### 问题4：Parquet文件读取错误
- **解决方案**：
  ```bash
  # 安装正确版本的pandas和pyarrow
  pip install pandas pyarrow fastparquet
  
  # 或者使用dask读取
  pip install dask[dataframe]
  ```

## 高级用法

### 自定义数据集

如果需要使用自定义数据集，可以修改配置文件：

```yaml
# configs/data/laion_filtered.yaml
dataset:
  name: "custom-dataset"
  path: "./data/custom"  # 修改路径
  metadata_file: "./data/custom/metadata.parquet"  # 修改元数据文件路径
```

### 数据集预处理

项目包含数据预处理模块：

```python
from src.data.preprocessing import get_transform

# 获取数据变换
transform = get_transform(config, mode='train')

# 创建数据集
from src.data.dataset import LAIONDataset
dataset = LAIONDataset(config, transform=transform, split='train')
```

### 批量下载图像

如果需要下载实际图像文件：

```python
import requests
from PIL import Image
from io import BytesIO
import pandas as pd

# 读取元数据
df = pd.read_parquet("./data/laion/metadata.parquet")

# 下载前N张图像
for i, row in df.head(10).iterrows():
    try:
        response = requests.get(row['url'], timeout=10)
        img = Image.open(BytesIO(response.content))
        img.save(f"./data/laion/images/image_{i:06d}.jpg")
        print(f"下载完成: {i}")
    except Exception as e:
        print(f"下载失败 {row['url']}: {e}")
```

## 性能优化建议

1. **使用缓存**：启用数据集缓存加速训练
   ```yaml
   preprocessing:
     use_cache: true
     cache_dir: "./data/cache"
   ```

2. **数据并行**：使用多个worker加载数据
   ```yaml
   loader:
     num_workers: 4
     prefetch_factor: 2
   ```

3. **内存映射**：对于大型数据集，使用内存映射文件
   ```python
   df = pd.read_parquet("metadata.parquet", memory_map=True)
   ```

## 参考资料

1. [LAION官方网站](https://laion.ai/)
2. [LAION数据集论文](https://arxiv.org/abs/2210.08402)
3. [Hugging Face数据集](https://huggingface.co/datasets/laion)
4. [img2dataset工具](https://github.com/rom1504/img2dataset)
5. [WebDataset格式](https://github.com/webdataset/webdataset)

## 技术支持

如果遇到问题：
1. 检查错误信息
2. 查看日志文件
3. 参考项目README
4. 在GitHub Issues中搜索类似问题
5. 创建新的Issue寻求帮助

---

**注意**：LAION数据集受版权法保护，请确保遵守使用条款和许可证要求。