```bash
npm install -g opencode-ai@latest
```

opencode 安装

eval $(curl -s http://deploy.i.shaipower.com/httpproxy)

```bash
# Linux
curl -sSfL https://github.com/peak/s5cmd/releases/download/v2.2.2/s5cmd_2.2.2_Linux-64bit.tar.gz | tar -xz
mv s5cmd /usr/local/bin/
```


```bash
export AWS_ACCESS_KEY_ID="x"
export AWS_SECRET_ACCESS_KEY="x"
# 设置 S3 区域（根据实际情况修改，如 cn-beijing, us-east-1 等）
export AWS_DEFAULT_REGION="us-east-1"
# 设置自定义 S3 endpoint URL（用于兼容 OSS 等 S3 兼容服务）
export AWS_ENDPOINT_URL="http://oss.i.x.com"
```

```bash
s5cmd --numworkers 4000 cp --concurrency 4000 /mnt/jfs6/ s3://shai-aos-general/jfs6-new/
```

s5cmd 批量s3数据传输

ms-swift q3 30a3b 训练记录

ms-swift export 导出packing数据：

```bash
# Qwen3-VL 多模态模型导出 cached_dataset
IMAGE_MAX_TOKEN_NUM=5000 \
MAX_PIXELS=1003520 \
VIDEO_MAX_TOKEN_NUM=128 \
FPS_MAX_FRAMES=16 \
swift export \
    --model /mnt/jfs6/model/Qwen3-VL-8B-Instruct/ \
    --dataset 'your_dataset_name' \
    --split_dataset_ratio 0 \
    --dataset_num_proc 16 \
    --max_length 10240 \
    --to_cached_dataset true \
    --output_dir /path/to/output/cached_dataset
```

训练时候使用：

```bash
# 训练时使用
IMAGE_MAX_TOKEN_NUM=5000 \
MAX_PIXELS=1003520 \
VIDEO_MAX_TOKEN_NUM=128 \
FPS_MAX_FRAMES=16 \
swift sft \
    --model /mnt/jfs6/model/Qwen3-VL-8B-Instruct/ \
    --cached_dataset '/mnt/jfs6/g-xiedong/cached_dataset/train' \
    --cached_val_dataset '/mnt/jfs6/g-xiedong/cached_dataset/val' \
    --packing true \
    --packing_num_proc 64 \
    --max_length 10240 \
```

IMAGE_MAX_TOKEN_NUM、max_length 需要一致 ！

ms-swift 数据打包（Packing）

1. 查找 nvidia-smi → 找到 /usr/local/nvidia/bin/nvidia-smi
2. 添加到 PATH → export PATH="/usr/local/nvidia/bin:$PATH"
3. 查找 CUDA 库 → 找到 /usr/local/nvidia/lib64
4. 设置 LD_LIBRARY_PATH → export LD_LIBRARY_PATH="/usr/local/nvidia/lib64:$LD_LIBRARY_PATH"
5. 设置 CUDA_HOME → export CUDA_HOME="/usr/local/cuda"



fix_nvidia_smi.sh 这个代码会直接全局看是否可以修复：
```bash
#!/bin/bash

# ============================================================================
# nvidia-smi and CUDA Driver Library Fix Script
# ============================================================================

set -e

echo "=========================================="
echo "Starting nvidia-smi and CUDA Driver Library Fix"
echo "=========================================="
echo ""

# ============================================================================
# 1. Find nvidia-smi command
# ============================================================================
find_nvidia_smi() {
    local paths=(
        "/usr/bin"
        "/usr/local/bin"
        "/usr/local/cuda/bin"
        "/usr/local/nvidia/bin"
        "/opt/nvidia/bin"
        "/bin"
    )
    
    for path in "${paths[@]}"; do
        if [ -f "$path/nvidia-smi" ] && [ -x "$path/nvidia-smi" ]; then
            echo "$path/nvidia-smi"
            return 0
        fi
    done
    
    # Try to find using find command across the system
    local found_path=$(find /usr /opt /bin -name "nvidia-smi" -type f -executable 2>/dev/null | head -1 || echo "")
    if [ -n "$found_path" ] && [ -f "$found_path" ]; then
        echo "$found_path"
        return 0
    fi
    
    # Try to find using which/whereis
    if command -v nvidia-smi >/dev/null 2>&1; then
        command -v nvidia-smi
        return 0
    fi
    
    return 1
}

echo "Step 1: Finding nvidia-smi command..."
NVIDIA_SMI_PATH=$(find_nvidia_smi || echo "")
if [ -n "$NVIDIA_SMI_PATH" ]; then
    echo "[OK] Found nvidia-smi: $NVIDIA_SMI_PATH"
    # Add nvidia-smi directory to PATH
    NVIDIA_SMI_DIR=$(dirname "$NVIDIA_SMI_PATH")
    export PATH="${NVIDIA_SMI_DIR}:${PATH}"
    echo "  Added $NVIDIA_SMI_DIR to PATH"
else
    echo "[FAIL] nvidia-smi command not found"
    echo "  Trying to find in common paths..."
    for path in /usr/bin /usr/local/bin /usr/local/cuda/bin /usr/local/nvidia/bin; do
        if [ -d "$path" ]; then
            echo "  Checking $path: $(ls -la "$path/nvidia-smi" 2>/dev/null || echo 'not found')"
        fi
    done
fi
echo ""

# ============================================================================
# 2. Find CUDA Driver Library (libcuda.so.1)
# ============================================================================
find_libcuda() {
    local paths=(
        "/usr/lib/x86_64-linux-gnu"
        "/usr/local/cuda/lib64"
        "/usr/lib64"
        "/usr/lib"
        "/lib/x86_64-linux-gnu"
        "/usr/local/nvidia/lib64"
        "/usr/local/nvidia/lib"
        "/opt/nvidia/lib64"
        "/opt/nvidia/lib"
    )
    
    for path in "${paths[@]}"; do
        if [ -f "$path/libcuda.so.1" ] || [ -f "$path/libcuda.so" ]; then
            echo "$path"
            return 0
        fi
    done
    
    # Try to find using find command across the system
    local found_path=$(find /usr /opt /lib -name "libcuda.so.1" 2>/dev/null | head -1 | xargs dirname 2>/dev/null || echo "")
    if [ -n "$found_path" ] && [ -d "$found_path" ]; then
        echo "$found_path"
        return 0
    fi
    
    # Try to find using ldconfig
    local libcuda_path=$(ldconfig -p 2>/dev/null | grep libcuda.so.1 | head -1 | awk '{print $4}' | xargs dirname 2>/dev/null || echo "")
    if [ -n "$libcuda_path" ] && [ -d "$libcuda_path" ]; then
        echo "$libcuda_path"
        return 0
    fi
    
    return 1
}

echo "Step 2: Finding CUDA Driver Library (libcuda.so.1)..."
CUDA_LIB_PATH=$(find_libcuda || echo "")
if [ -n "$CUDA_LIB_PATH" ]; then
    echo "[OK] Found CUDA driver library path: $CUDA_LIB_PATH"
    export LD_LIBRARY_PATH="${CUDA_LIB_PATH}:${LD_LIBRARY_PATH}"
    echo "  Added $CUDA_LIB_PATH to LD_LIBRARY_PATH"
else
    echo "[WARN] libcuda.so.1 not found"
    echo "  Diagnostic information:"
    echo "    - Check /usr/lib/x86_64-linux-gnu/libcuda.so*: $(ls /usr/lib/x86_64-linux-gnu/libcuda.so* 2>/dev/null | head -1 || echo 'not found')"
    echo "    - Check /usr/local/cuda/lib64/libcuda.so*: $(ls /usr/local/cuda/lib64/libcuda.so* 2>/dev/null | head -1 || echo 'not found')"
    echo "    - Check /usr/local/nvidia/lib64/libcuda.so*: $(ls /usr/local/nvidia/lib64/libcuda.so* 2>/dev/null | head -1 || echo 'not found')"
    echo "    - libcuda in ldconfig: $(ldconfig -p 2>/dev/null | grep libcuda || echo 'not found')"
    echo ""
    echo "  Trying to use default paths and set environment variables..."
    # Try common paths
    export LD_LIBRARY_PATH="/usr/lib/x86_64-linux-gnu:/usr/local/cuda/lib64:/usr/lib64:/usr/local/nvidia/lib64:${LD_LIBRARY_PATH}"
fi
echo ""

# ============================================================================
# 3. Check /dev/nvidia* devices
# ============================================================================
echo "Step 3: Checking /dev/nvidia* devices..."
if ls /dev/nvidia* >/dev/null 2>&1; then
    echo "[OK] Found /dev/nvidia* devices:"
    ls -la /dev/nvidia* 2>/dev/null | head -5 || true
else
    echo "[WARN] /dev/nvidia* devices not found"
    echo "  This may indicate GPU devices are not properly mounted in container"
fi
echo ""

# ============================================================================
# 4. Set CUDA_HOME (if not set)
# ============================================================================
echo "Step 4: Setting CUDA_HOME..."
if [ -z "$CUDA_HOME" ]; then
    if [ -d "/usr/local/cuda" ]; then
        export CUDA_HOME="/usr/local/cuda"
        export PATH="${CUDA_HOME}/bin:${PATH}"
        export LD_LIBRARY_PATH="${CUDA_HOME}/lib64:${LD_LIBRARY_PATH}"
        echo "[OK] Set CUDA_HOME=$CUDA_HOME"
    elif [ -d "/usr/local/nvidia" ]; then
        export CUDA_HOME="/usr/local/nvidia"
        export PATH="${CUDA_HOME}/bin:${PATH}"
        export LD_LIBRARY_PATH="${CUDA_HOME}/lib64:${LD_LIBRARY_PATH}"
        echo "[OK] Set CUDA_HOME=$CUDA_HOME"
    else
        echo "[WARN] CUDA installation directory not found"
    fi
else
    echo "[OK] CUDA_HOME already set: $CUDA_HOME"
fi
echo ""

# ============================================================================
# 5. Verify CUDA library accessibility
# ============================================================================
echo "Step 5: Verifying CUDA driver library accessibility..."
CUDA_LIB_OK=false
if python3 << 'PYEOF' 2>/dev/null | grep -q "OK"; then
import ctypes
try:
    ctypes.CDLL("libcuda.so.1")
    print("OK")
except:
    print("FAIL")
PYEOF
    CUDA_LIB_OK=true
fi

if [ "$CUDA_LIB_OK" = "true" ]; then
    echo "[OK] CUDA driver library is accessible"
else
    echo "[WARN] CUDA driver library may not be accessible, trying other fix methods..."
    
    # Try to detect CUDA through PyTorch (if PyTorch is available, CUDA runtime exists)
    if python3 << 'PYEOF' 2>/dev/null | grep -q "True"; then
import torch
print("PyTorch CUDA available:", torch.cuda.is_available())
PYEOF
        echo "[OK] PyTorch can access CUDA, setting vLLM environment variables to force GPU usage"
        # Set vLLM related environment variables to force GPU usage
        export VLLM_USE_CPU=0
        export VLLM_WORKER_MULTIPROC_METHOD=spawn
        # Try to set device related environment variables
        export CUDA_DEVICE_ORDER=PCI_BUS_ID
    else
        echo "[FAIL] PyTorch cannot access CUDA either"
    fi
fi
echo ""

# ============================================================================
# 6. Test nvidia-smi command
# ============================================================================
echo "Step 6: Testing nvidia-smi command..."
if command -v nvidia-smi >/dev/null 2>&1; then
    echo "[OK] nvidia-smi command is available"
    echo ""
    echo "Running nvidia-smi test:"
    echo "----------------------------------------"
    if nvidia-smi >/dev/null 2>&1; then
        nvidia-smi
        echo "----------------------------------------"
        echo "[OK] nvidia-smi ran successfully!"
    else
        echo "[FAIL] nvidia-smi execution failed"
        echo "  Error information:"
        nvidia-smi 2>&1 || true
    fi
else
    echo "[FAIL] nvidia-smi command is still not available"
    echo "  Current PATH: $PATH"
    echo "  Trying to use full path directly:"
    if [ -n "$NVIDIA_SMI_PATH" ] && [ -f "$NVIDIA_SMI_PATH" ]; then
        echo "  Using: $NVIDIA_SMI_PATH"
        "$NVIDIA_SMI_PATH" || true
    fi
fi
echo ""

# ============================================================================
# 7. Output environment variables summary
# ============================================================================
echo "=========================================="
echo "Environment Variables Summary"
echo "=========================================="
echo "PATH: $PATH"
echo "LD_LIBRARY_PATH: $LD_LIBRARY_PATH"
echo "CUDA_HOME: ${CUDA_HOME:-not set}"
echo "NVIDIA_SMI_PATH: ${NVIDIA_SMI_PATH:-not found}"
echo "CUDA_LIB_PATH: ${CUDA_LIB_PATH:-not found}"
echo "=========================================="
echo ""

# ============================================================================
# 8. Generate persistent environment variable setup script
# ============================================================================
ENV_SCRIPT="/tmp/setup_nvidia_env.sh"
cat > "$ENV_SCRIPT" << 'ENVEOF'
#!/bin/bash
# Auto-generated environment variable setup script
# Source this file in training scripts to apply fixes

# Set PATH
if [ -n "$NVIDIA_SMI_DIR" ]; then
    export PATH="${NVIDIA_SMI_DIR}:${PATH}"
fi

# Set LD_LIBRARY_PATH
if [ -n "$CUDA_LIB_PATH" ]; then
    export LD_LIBRARY_PATH="${CUDA_LIB_PATH}:${LD_LIBRARY_PATH}"
fi

# Set CUDA_HOME
if [ -z "$CUDA_HOME" ] && [ -d "/usr/local/cuda" ]; then
    export CUDA_HOME="/usr/local/cuda"
    export PATH="${CUDA_HOME}/bin:${PATH}"
    export LD_LIBRARY_PATH="${CUDA_HOME}/lib64:${LD_LIBRARY_PATH}"
fi

# Set vLLM related environment variables
export VLLM_USE_CPU=0
export VLLM_WORKER_MULTIPROC_METHOD=spawn
export CUDA_DEVICE_ORDER=PCI_BUS_ID
ENVEOF

# Replace variables in script
if [ -n "$NVIDIA_SMI_DIR" ]; then
    sed -i "s|NVIDIA_SMI_DIR|\"$NVIDIA_SMI_DIR\"|g" "$ENV_SCRIPT"
fi
if [ -n "$CUDA_LIB_PATH" ]; then
    sed -i "s|CUDA_LIB_PATH|\"$CUDA_LIB_PATH\"|g" "$ENV_SCRIPT"
fi

chmod +x "$ENV_SCRIPT"
echo "[OK] Generated environment variable setup script: $ENV_SCRIPT"
echo "  Use in training scripts: source $ENV_SCRIPT"
echo ""

echo "=========================================="
echo "Fix completed!"
echo "=========================================="
echo ""
echo "If nvidia-smi is still not available, please check:"
echo "1. Whether GPU devices (/dev/nvidia*) are properly mounted in container"
echo "2. Whether container image contains NVIDIA driver tools"
echo "3. Whether rjob configuration correctly sets GPU resources"
echo ""

```

diagnose_nvidia_env.sh 这个代码会诊断环境：

```bash
#!/bin/bash

# ============================================================================
# NVIDIA/CUDA Environment Diagnostic Script
# Run this script and provide the output to get hardcoded environment variables
# ============================================================================

echo "=========================================="
echo "NVIDIA/CUDA Environment Diagnostic"
echo "=========================================="
echo ""
echo "Please run this script and provide the complete output."
echo ""

# 1. Find nvidia-smi
echo "=== 1. NVIDIA-SMI LOCATION ==="
NVIDIA_SMI_PATH=""
for path in /usr/local/nvidia/bin /usr/bin /usr/local/bin /usr/local/cuda/bin /opt/nvidia/bin /bin; do
    if [ -f "$path/nvidia-smi" ] && [ -x "$path/nvidia-smi" ]; then
        NVIDIA_SMI_PATH="$path/nvidia-smi"
        NVIDIA_SMI_DIR="$path"
        echo "FOUND: $NVIDIA_SMI_PATH"
        echo "DIR: $NVIDIA_SMI_DIR"
        break
    fi
done

if [ -z "$NVIDIA_SMI_PATH" ]; then
    echo "NOT FOUND: Searching with find..."
    NVIDIA_SMI_PATH=$(find /usr /opt /bin -name "nvidia-smi" -type f -executable 2>/dev/null | head -1 || echo "")
    if [ -n "$NVIDIA_SMI_PATH" ]; then
        NVIDIA_SMI_DIR=$(dirname "$NVIDIA_SMI_PATH")
        echo "FOUND: $NVIDIA_SMI_PATH"
        echo "DIR: $NVIDIA_SMI_DIR"
    else
        echo "NOT FOUND: nvidia-smi not found in system"
    fi
fi
echo ""

# 2. Find CUDA driver library
echo "=== 2. CUDA DRIVER LIBRARY (libcuda.so.1) ==="
CUDA_LIB_PATH=""
for path in /usr/local/nvidia/lib64 /usr/lib/x86_64-linux-gnu /usr/local/cuda/lib64 /usr/lib64 /usr/lib /lib/x86_64-linux-gnu /opt/nvidia/lib64; do
    if [ -f "$path/libcuda.so.1" ] || [ -f "$path/libcuda.so" ]; then
        CUDA_LIB_PATH="$path"
        echo "FOUND: $CUDA_LIB_PATH"
        ls -la "$path/libcuda.so"* 2>/dev/null | head -3 || true
        break
    fi
done

if [ -z "$CUDA_LIB_PATH" ]; then
    echo "NOT FOUND: Searching with find..."
    CUDA_LIB_PATH=$(find /usr /opt /lib -name "libcuda.so.1" 2>/dev/null | head -1 | xargs dirname 2>/dev/null || echo "")
    if [ -n "$CUDA_LIB_PATH" ]; then
        echo "FOUND: $CUDA_LIB_PATH"
        ls -la "$CUDA_LIB_PATH/libcuda.so"* 2>/dev/null | head -3 || true
    else
        echo "NOT FOUND: libcuda.so.1 not found"
    fi
fi
echo ""

# 2.5. Find libnvidia-ml.so (required by nvidia-smi)
echo "=== 2.5. NVIDIA ML LIBRARY (libnvidia-ml.so) ==="
NVIDIA_ML_LIB_PATH=""
for path in /usr/local/nvidia/lib64 /usr/lib/x86_64-linux-gnu /usr/local/cuda/lib64 /usr/lib64 /usr/lib /lib/x86_64-linux-gnu /opt/nvidia/lib64; do
    if [ -f "$path/libnvidia-ml.so" ] || [ -f "$path/libnvidia-ml.so.1" ]; then
        NVIDIA_ML_LIB_PATH="$path"
        echo "FOUND: $NVIDIA_ML_LIB_PATH"
        ls -la "$path/libnvidia-ml.so"* 2>/dev/null | head -3 || true
        break
    fi
done

if [ -z "$NVIDIA_ML_LIB_PATH" ]; then
    echo "NOT FOUND: Searching with find..."
    NVIDIA_ML_LIB_PATH=$(find /usr /opt /lib -name "libnvidia-ml.so*" 2>/dev/null | head -1 | xargs dirname 2>/dev/null || echo "")
    if [ -n "$NVIDIA_ML_LIB_PATH" ]; then
        echo "FOUND: $NVIDIA_ML_LIB_PATH"
        ls -la "$NVIDIA_ML_LIB_PATH/libnvidia-ml.so"* 2>/dev/null | head -3 || true
    else
        echo "NOT FOUND: libnvidia-ml.so not found (this may cause nvidia-smi to fail)"
    fi
fi
echo ""

# 3. Check CUDA_HOME
echo "=== 3. CUDA_HOME ==="
if [ -d "/usr/local/cuda" ]; then
    echo "FOUND: /usr/local/cuda"
    echo "BIN: /usr/local/cuda/bin"
    echo "LIB64: /usr/local/cuda/lib64"
elif [ -d "/usr/local/nvidia" ]; then
    echo "FOUND: /usr/local/nvidia"
    echo "BIN: /usr/local/nvidia/bin"
    echo "LIB64: /usr/local/nvidia/lib64"
else
    echo "NOT FOUND: No CUDA installation directory found"
fi
echo ""

# 4. Check GPU devices
echo "=== 4. GPU DEVICES ==="
if ls /dev/nvidia* >/dev/null 2>&1; then
    echo "FOUND: /dev/nvidia* devices"
    ls -la /dev/nvidia* 2>/dev/null | head -5
else
    echo "NOT FOUND: No /dev/nvidia* devices"
fi
echo ""

# 5. Check ldconfig
echo "=== 5. LDCONFIG LIBRARY PATHS ==="
if command -v ldconfig >/dev/null 2>&1; then
    echo "libcuda libraries in ldconfig:"
    ldconfig -p 2>/dev/null | grep libcuda || echo "  No libcuda found in ldconfig"
else
    echo "ldconfig command not available"
fi
echo ""

# 6. Current environment variables
echo "=== 6. CURRENT ENVIRONMENT VARIABLES ==="
echo "PATH: $PATH"
echo "LD_LIBRARY_PATH: $LD_LIBRARY_PATH"
echo "CUDA_HOME: ${CUDA_HOME:-not set}"
echo ""

# 7. Test nvidia-smi if found
echo "=== 7. NVIDIA-SMI TEST ==="
if [ -n "$NVIDIA_SMI_PATH" ] && [ -f "$NVIDIA_SMI_PATH" ]; then
    echo "Testing: $NVIDIA_SMI_PATH"
    if "$NVIDIA_SMI_PATH" --version >/dev/null 2>&1; then
        echo "SUCCESS: nvidia-smi works"
        "$NVIDIA_SMI_PATH" --version 2>&1 | head -1
    else
        echo "FAILED: nvidia-smi found but cannot execute"
        "$NVIDIA_SMI_PATH" --version 2>&1 || true
    fi
else
    echo "SKIPPED: nvidia-smi not found"
fi
echo ""

# 8. Summary
echo "=========================================="
echo "SUMMARY FOR HARDCODING"
echo "=========================================="
echo "NVIDIA_SMI_DIR=${NVIDIA_SMI_DIR:-NOT_FOUND}"
echo "CUDA_LIB_PATH=${CUDA_LIB_PATH:-NOT_FOUND}"
echo "NVIDIA_ML_LIB_PATH=${NVIDIA_ML_LIB_PATH:-NOT_FOUND}"
echo "CUDA_HOME=${CUDA_HOME:-/usr/local/cuda}"
echo "=========================================="
echo ""
echo "Please provide the complete output above to get hardcoded environment variables."

```


导出这些环境变量即可，把这些环境变量加入：
```bash
# NVIDIA-SMI 路径
export PATH="/usr/local/nvidia/bin:${PATH}"

# CUDA driver 库路径（包含 libcuda.so.1 和 libnvidia-ml.so）
export LD_LIBRARY_PATH="/usr/local/nvidia/lib64:${LD_LIBRARY_PATH}"

# CUDA 安装目录
export CUDA_HOME="/usr/local/cuda"
export PATH="${CUDA_HOME}/bin:${PATH}"
export LD_LIBRARY_PATH="${CUDA_HOME}/lib64:${LD_LIBRARY_PATH}"

# vLLM 相关环境变量（可选）
export VLLM_USE_CPU=0
export VLLM_WORKER_MULTIPROC_METHOD=spawn
export CUDA_DEVICE_ORDER=PCI_BUS_ID
```

修复nvidia-smi无法找到的问题

# MS-SWIFT 数据处理流程详解

本文档详细说明从原始数据到训练的完整数据处理流程，包括每个步骤的参数控制和效果说明。

---

## 流程概览

```
原始数据集 (dataset_info.json)
    ↓ 
① 数据加载 (DatasetLoader)
    ↓
② 数据预处理 (MessagesPreprocessor)
    ├── mask_history_sample 拆分 (可选)
    └── 格式标准化
    ↓
③ 长度过滤 (_select_dataset)
    ↓
④ 数据集划分 (split_dataset_ratio)
    ├── 训练集
    └── 验证集
    ↓
⑤ 数据编码 (Template.encode)
    ↓
⑥ 数据打包 (PackingDataset) (可选)
    ↓
⑦ 迭代次数计算 (train_iters)
    ↓
开始训练
```

---

## 详细流程说明

### ① 数据加载 (DatasetLoader)

**功能**：从本地或远程加载原始数据集

**相关参数**：
- `dataset`: 数据集ID或路径列表
  - 格式: `dataset_id:subset#count`
  - 示例: `mmdu_val` 或 `/path/to/dataset.json`
- `custom_dataset_info`: 自定义数据集配置文件路径
- `dataset_num_proc`: 数据加载的进程数（默认1）
- `load_from_cache_file`: 是否使用缓存（默认False，建议生产环境设True）
- `streaming`: 是否流式加载（默认False）

**效果**：
- 加载原始JSON/JSONL数据
- 注册自定义数据集配置
- 返回HuggingFace Dataset对象

**示例日志**：
```
[INFO:swift] Successfully registered `/path/to/dataset_info.json`.
```

---

### ② 数据预处理 (MessagesPreprocessor)

#### 2.1 mask_history_sample 拆分 (可选)

**功能**：将多轮对话样本拆分为多个训练样本，模拟渐进式对话训练

**相关参数**：
- `mask_history_sample`: 是否启用拆分（默认False）
- `max_human_steps`: 每个拆分样本最多保留几轮对话（默认-1，不限制）
- `media_dir`: 多模态数据（图片/视频）所在目录

**拆分逻辑**：
假设原始对话有N轮（N个user + N个assistant消息）：
- 拆分为N个训练样本
- 第1个样本：包含前1轮对话（最多保留max_human_steps轮历史）
- 第2个样本：包含前2轮对话
- 第N个样本：包含全部N轮对话

**效果**：
- 样本数扩增：110 → 1645（扩增比例14.95x）
- 每个样本标记 `_mask_history_sample` 字段用于后续处理

**示例日志**：
```
[INFO:swift] [数据集拆分] 启用mask_history_sample模式: mask_history_sample=True, max_human_steps=2
[INFO:swift] [数据集拆分] 每个多轮对话样本将被拆分为多个训练样本,每个样本最多保留2个human步骤
[INFO:swift] [数据集拆分] 预处理前数据集大小: 110 个样本
[INFO:swift] [数据集拆分] 预处理后数据集大小: 1645 个样本
[INFO:swift] [数据集拆分] 样本数量变化: 110 -> 1645 (增加了 1535 个样本, 扩增比例: 14.95x)
```

**适用场景**：
- 多轮对话任务
- 需要模型学习渐进式对话能力
- 增加训练样本多样性

MS-SWIFT支持在messages中通过 loss 字段控制单个样本的损失：


```bash
{
  "messages": [
    {"role": "user", "content": "问题"},
    {"role": "assistant", "content": "回答", "loss": 0.0}  // 不计算损失
  ]
}
```

Loss Scale 策略说明

| 策略 | 说明 | 适用场景 |
|-----|-----|---------|
| `default` | 所有assistant回复都计算损失（不包括system/user） | 标准SFT训练 |
| `last_round` | 只有最后一轮assistant回复计算损失 | RLHF、mask_history_sample拆分的数据 |
| `all` | 所有tokens都计算损失（包括system/user） | 预训练 |



数据集组织：
```bash
{
  "example_masked_dataset": {
    "file_name": "example_data.json",
    "formatting": "sharegpt",
    "mask_history_sample": true,
    "max_human_steps": 2,
    "loss_scale": "last_round",
    "columns": {
      "messages": "conversations"
    },
    "tags": {
      "role_tag": "from",
      "content_tag": "value",
      "user_tag": "user",
      "assistant_tag": "assistant"
    }
  },
  "example_normal_dataset": {
    "file_name": "normal_sft.json",
    "formatting": "sharegpt"
  }
}


```

#### 2.2 格式标准化

**功能**：将不同格式的对话数据统一为标准messages格式

**支持格式**：
- OpenAI格式: `[{"role": "user", "content": "..."}]`
- ShareGPT格式: `[{"from": "human", "value": "..."}]`
- 自定义格式（通过columns参数映射）

**相关参数**：
- `columns`: JSON字符串，用于列名映射
  - 示例: `'{"text1": "query", "text2": "response"}'`

---

### ③ 长度过滤 (_select_dataset)

**功能**：过滤掉超过最大长度的样本

**相关参数**：
- `max_length`: 最大序列长度（如2048）

**过滤逻辑**：
```python
# 保留 length <= max_length 的样本
idxs = [i for i, length in enumerate(dataset['length'])
        if (max(length) if isinstance(length, list) else length) <= max_length]
```

**效果**：
- 样本数减少：1645 → 101（过滤掉1544个超长样本）

**示例日志**：
```
[INFO:swift] Dataset filtered, origin length: 1645, filtered dataset length: 101
```

**说明**：
- 多模态数据length可能是列表（多个图片/视频对应多个长度）
- 单模态数据length是整数
- 过滤发生在tokenize之前，基于预估长度



---

### ④ 数据集划分 (split_dataset_ratio)

**功能**：将数据集划分为训练集和验证集

**相关参数**：
- `split_dataset_ratio`: 验证集比例（0.0-1.0）
  - 0.0: 不划分，全部用于训练
  - 0.01: 1%用于验证，99%用于训练
  - 1.0: 全部用于验证
- `val_dataset`: 独立验证集（如指定此参数，则split_dataset_ratio自动设为0）
- `dataset_shuffle`: 是否在划分前打乱（默认True）
- `data_seed`: 随机种子（默认42）

**划分逻辑**：
```python
# 假设过滤后有103个样本，split_dataset_ratio=0.01
dataset_len = 103
val_sample = max(int(103 * 0.01), 1) = 1
train_sample = 103 - 1 = 102

# 使用train_test_split划分
train_dataset, val_dataset = dataset.train_test_split(
    test_size=1, shuffle=True, seed=42
)
```

**效果**：
- 训练集：101个样本
- 验证集：2个样本

**示例日志**：
```
[INFO:swift] train_dataset: Dataset({
    features: ['messages', 'images', '_mask_history_sample', 'length'],
    num_rows: 101
})
[INFO:swift] val_dataset: Dataset({
    features: ['messages', 'images', '_mask_history_sample', 'length'],
    num_rows: 2
})
```

**注意事项**：
- `val_dataset` 会自动保存到输出目录：`{output_dir}/val_dataset.jsonl`
- 如果同时设置了`val_dataset`参数，则`split_dataset_ratio`会被忽略

---

### ⑤ 数据编码 (Template.encode)

**功能**：将文本转换为token IDs，处理多模态数据

**相关参数**：
- `lazy_tokenize`: 是否延迟编码
  - False: 训练前一次性编码所有样本（默认，LLM推荐）
  - True: 训练时动态编码（MLLM默认，节省内存）
- `num_proc`: 编码进程数（即`dataset_num_proc`）

**处理内容**：
- Tokenization: 文本 → token IDs
- 多模态编码：图片/视频 → 模型输入格式
- 添加特殊token（如BOS、EOS）
- 计算精确的token长度

**效果**：
- 为每个样本生成 `input_ids`, `labels`, `attention_mask` 等字段
- 更新 `length` 字段为精确token长度

---

### ⑥ 数据打包 (PackingDataset) (可选)

**功能**：将多个短样本合并为接近max_length的长样本，提高GPU利用率

**相关参数**：
- `packing`: 是否启用打包（默认False）
- `packing_length`: 打包目标长度（默认等于max_length）
- `packing_num_proc`: 打包进程数（默认1）

**打包逻辑**：
```python
# 自动限制进程数
packing_num_proc = min(配置值, math.ceil(len(dataset) / 1000))

# 示例：101个样本
packing_num_proc = min(8, math.ceil(101 / 1000)) = min(8, 1) = 1
```

**打包算法**：
- 使用贪心算法将多个样本打包到接近packing_length
- 保证不切分完整序列
- 使用Flash Attention确保packed样本内序列互不可见

**效果**：
- 样本数减少：101 → 86（打包效率：~85%）
- GPU利用率提升，显存占用更稳定
- 训练速度提升（减少padding浪费）

**示例日志**：
```
[INFO:swift] ================================================================================
[INFO:swift] 数据打包(Packing)处理详情：
[INFO:swift] --------------------------------------------------------------------------------
[INFO:swift]   数据集样本总数: 101
[INFO:swift]   数据长度列表总数: 101
[INFO:swift]   最大打包长度(packing_length): 2048
[INFO:swift]   打包进程数(packing_num_proc): 1
[INFO:swift]   每批次处理大小(PACKING_BATCH_SIZE): 1000
[INFO:swift]   严格模式(strict): False
[INFO:swift]   开始使用 1 个进程并行打包 101 条数据...
[INFO:swift] ================================================================================
Packing: 100%|██████████| 101/101 [00:00<00:00, 10425.38it/s]
```

**注意事项**：
- Packing会减少样本数，需相应调整学习率和梯度累加步数
- 打包进程数自动限制：每1000个样本最多1个进程
- 不适合需要精确控制样本顺序的场景

---

### ⑦ 迭代次数计算 (train_iters)

**功能**：计算总训练迭代次数

**相关参数**：
- `max_epochs`: 训练轮数
- `global_batch_size`: 全局批次大小
- `micro_batch_size`: 每个GPU的批次大小
- `tensor_model_parallel_size`: 张量并行大小
- `world_size`: 总GPU数（NPROC_PER_NODE）

**计算逻辑**：

```python
# 步骤1：计算数据并行大小
data_parallel_size = world_size // tensor_model_parallel_size
# 示例：8 // 4 = 2

# 步骤2：计算step批次大小
step_batch_size = micro_batch_size × data_parallel_size
# 示例：1 × 2 = 2

# 步骤3：对齐数据集样本数（向下取整到step_batch_size的倍数）
dataset_sample = (len(train_dataset) // step_batch_size) × step_batch_size × num_generations
# 示例：(86 // 2) × 2 × 1 = 43 × 2 × 1 = 86

# 步骤4：计算总迭代次数
train_iters = (dataset_sample × max_epochs) // global_batch_size
# 示例：(86 × 10) // 8 = 860 // 8 = 107
```

**效果**：
- 总迭代次数：107
- 每个epoch：10.7次迭代
- 总训练样本数：860个（86样本 × 10轮）

**示例日志**：
```
[INFO:swift] ================================================================================
[INFO:swift] 总迭代次数(train_iters)计算详情：
[INFO:swift] --------------------------------------------------------------------------------
[INFO:swift]   数据集总样本数(len(train_dataset)): 86
[INFO:swift]   micro_batch_size: 1
[INFO:swift]   data_parallel_size(数据并行数): 2
[INFO:swift]   step_batch_size = micro_batch_size × data_parallel_size = 1 × 2 = 2
[INFO:swift]   num_generations(每个样本生成次数): 1
[INFO:swift]   dataset_sample = (dataset_len // step_batch_size) × step_batch_size × num_generations
[INFO:swift]                  = (86 // 2) × 2 × 1
[INFO:swift]                  = 43 × 2 × 1
[INFO:swift]                  = 86
[INFO:swift]   max_epochs(训练轮数): 10
[INFO:swift]   global_batch_size(全局批次大小): 8
[INFO:swift]   train_iters = (dataset_sample × max_epochs) // global_batch_size
[INFO:swift]               = (86 × 10) // 8
[INFO:swift]               = 860 // 8
[INFO:swift]               = 107
[INFO:swift] ================================================================================
```

**参数说明**：
- `num_generations`: RLHF任务中每个样本生成多个响应，SFT任务为1
- 对齐操作会丢弃无法凑成完整step_batch的样本

---

## 完整示例

以你的训练配置为例，展示完整的数据处理流程：

### 配置参数
```yaml
# qwen3_vl_8b_train_swanlab.yaml
dataset: mmdu_val
max_length: 2048
split_dataset_ratio: 0.01
packing: true
micro_batch_size: 1
global_batch_size: 8
max_epochs: 10
tensor_model_parallel_size: 4
dataset_num_proc: 8
```

### 处理流程

| 步骤 | 操作 | 样本数 | 说明 |
|-----|-----|-------|-----|
| 0 | 原始数据 | 110 | mmdu_val数据集 |
| 1 | mask_history_sample拆分 | 1645 | 扩增14.95倍 |
| 2 | 长度过滤 (>2048) | 103 | 过滤1542个超长样本 |
| 3 | 数据集划分 (1% val) | 101 (train) + 2 (val) | 1个验证样本，102个训练样本 |
| 4 | Packing打包 | 86 | 打包效率85% |
| 5 | 对齐到step_batch_size | 86 | 无损失（86是2的倍数） |
| 6 | 计算迭代次数 | - | 107次迭代 = (86×10)//8 |

### 训练统计
- **单epoch样本数**：86
- **单epoch迭代数**：10.7 (86×1//8)
- **总迭代次数**：107
- **总训练样本数**：860 (86×10)

---

## 常见问题

### Q1: 为什么打包进程数只有1？
**A**: 打包进程数自动限制为 `min(packing_num_proc, ceil(len(dataset)/1000))`。当样本数<1000时，只会使用1个进程。这是合理的，因为打包速度通常远快于tokenize速度。

### Q2: Packing会损失多少样本？
**A**: 取决于样本长度分布。通常损失10-20%。可以通过调整学习率和梯度累加来补偿。建议公式：
```
新学习率 = 原学习率 × (packing后样本数 / packing前样本数)
```

### Q3: mask_history_sample适用于哪些场景？
**A**: 适用于：
- 多轮对话训练
- 需要模型学习渐进式对话能力
- 样本量较少，需要数据增强

不适用于：
- 单轮问答任务
- 已有充足样本的场景

### Q4: split_dataset_ratio如何设置？
**A**: 建议值：
- 大数据集（>10k样本）：0.01-0.05
- 中型数据集（1k-10k）：0.05-0.1
- 小数据集（<1k）：0.1-0.2
- 如有独立验证集，设为0.0

### Q5: 如何提高数据处理速度？
**A**: 
1. 设置 `load_from_cache_file: true`（生产环境）
2. 增大 `dataset_num_proc`（纯文本推荐4-8）
3. 多模态模型谨慎使用多进程（可能更慢）
4. 设置 `OMP_NUM_THREADS` 环境变量限制OpenMP线程数

### Q6: 为什么训练样本数从101变成86？
**A**: 启用了Packing。Packing将多个短样本合并，减少样本数但提高GPU利用率。这是正常的，不是bug。

---

## 参数速查表

### 数据加载相关
| 参数 | 默认值 | 说明 |
|-----|-------|-----|
| `dataset` | [] | 数据集ID或路径列表 |
| `custom_dataset_info` | [] | 自定义数据集配置 |
| `dataset_num_proc` | 1 | 预处理进程数 |
| `load_from_cache_file` | False | 是否使用缓存 |
| `streaming` | False | 是否流式加载 |
| `data_seed` | 42 | 随机种子 |

### 数据预处理相关
| 参数 | 默认值 | 说明 |
|-----|-------|-----|
| `mask_history_sample` | False | 是否拆分多轮对话 |
| `max_human_steps` | -1 | 每个样本最多保留轮数 |
| `media_dir` | None | 多模态数据目录 |
| `columns` | None | 列名映射 |
| `max_length` | 2048 | 最大序列长度 |

### 数据集划分相关
| 参数 | 默认值 | 说明 |
|-----|-------|-----|
| `split_dataset_ratio` | 0.0 | 验证集比例 |
| `val_dataset` | [] | 独立验证集 |
| `dataset_shuffle` | True | 是否打乱数据集 |

### 数据打包相关
| 参数 | 默认值 | 说明 |
|-----|-------|-----|
| `packing` | False | 是否启用打包 |
| `packing_length` | None | 打包长度（None=max_length） |
| `packing_num_proc` | 1 | 打包进程数 |

### 训练迭代相关
| 参数 | 默认值 | 说明 |
|-----|-------|-----|
| `max_epochs` | - | 训练轮数 |
| `micro_batch_size` | 1 | 单GPU批次大小 |
| `global_batch_size` | - | 全局批次大小 |
| `tensor_model_parallel_size` | 1 | 张量并行大小 |

---

## 总结

MS-SWIFT的数据处理流程设计合理，支持多种优化策略：

1. **mask_history_sample**：有效扩增多轮对话样本
2. **长度过滤**：自动去除不合适的样本
3. **智能划分**：灵活的训练/验证集划分
4. **Packing优化**：提高GPU利用率，加速训练
5. **详细日志**：每个步骤都有清晰的日志输出

合理配置这些参数，可以在数据质量、训练效率和模型效果之间取得最佳平衡。



MS-SWIFT 数据处理流程详解

# MS-SWIFT 数据缓存机制详解

## 1. 总体缓存架构

MS-SWIFT 的数据缓存分为三个层次:
1. **数据预处理缓存** (HuggingFace Datasets Arrow格式)
2. **Packing数据缓存** (Megatron模式专用)
3. **媒体资源缓存** (图片/视频等多模态数据)



---

## 2. 数据预处理缓存 (最常用)

### 2.1 缓存位置

数据预处理后的缓存使用 **HuggingFace Datasets** 的Arrow格式缓存。

**默认缓存目录:**
```python
# 通过 modelscope 的 get_cache_dir() 获取
from modelscope.hub.utils.utils import get_cache_dir

cache_dir = get_cache_dir()  # 默认: ~/.cache/modelscope/
dataset_cache = os.path.join(cache_dir, 'datasets', 'map_cache')
```

**实际路径:**
```
~/.cache/modelscope/datasets/map_cache/
```

或者在你的环境中可能是:
```
/mnt/jfs6/g-xiedong/.cache/modelscope/datasets/map_cache/
```

### 2.2 缓存机制

缓存文件名基于数据集的 **fingerprint** (指纹)生成:

```python
# 代码位置: swift/llm/dataset/preprocessor/core.py
if isinstance(dataset, HfDataset) and not dataset.cache_files:
    map_kwargs['cache_file_name'] = os.path.join(
        get_cache_dir(), 
        'datasets', 
        'map_cache',
        f'{dataset._fingerprint}.arrow'  # 使用数据集指纹作为文件名
    )
```

**缓存文件示例:**
```
~/.cache/modelscope/datasets/map_cache/
├── abc123def456.arrow  # 预处理后的数据集1
├── xyz789uvw012.arrow  # 预处理后的数据集2
└── ...
```

### 2.3 控制缓存行为

#### 通过配置参数控制:

在你的 `qwen3_vl_8b_train_swanlab.yaml` 中:
```yaml
load_from_cache_file: true   # 启用缓存 (默认)
# load_from_cache_file: false  # 禁用缓存,每次重新处理
```

#### 通过环境变量控制缓存目录:

```bash
# 在 train_swanlab.sh 中设置
export MODELSCOPE_CACHE=/mnt/jfs6/g-xiedong/.cache/modelscope
```

### 2.4 缓存工作流程

1. **首次运行:**
   - 读取原始数据 (jsonl/json)
   - 应用预处理 (MessagesPreprocessor)
   - 如果启用 `mask_history_sample`,进行样本拆分
   - 将处理后的数据写入 `.arrow` 缓存文件
   - 训练使用缓存数据

2. **后续运行:**
   - 检查缓存文件是否存在
   - 如果存在且 `load_from_cache_file=true`,直接加载缓存
   - 跳过预处理步骤,直接训练

3. **缓存失效条件:**
   - 原始数据文件改变
   - 预处理代码改变
   - dataset_info.json 配置改变
   - 手动删除缓存文件

---

## 3. Packing 数据缓存 (Megatron专用)

### 3.1 什么是Packing?

在你的配置中:
```yaml
packing: true  # 启用packing
```

Packing 将多个短样本打包到一个序列中,提高训练效率,减少padding浪费。

### 3.2 Packing 缓存位置

**默认目录:**
```python
# 代码位置: swift/llm/dataset/indexed_dataset.py
cache_dir = os.getenv('PACKING_CACHE') or os.path.join(get_cache_dir(), 'tmp')
cache_dir = os.path.join(cache_dir, dataset_name)
```

**实际路径:**
```
~/.cache/modelscope/tmp/<dataset_name>/
```

或通过环境变量自定义:
```bash
export PACKING_CACHE=/mnt/jfs6/g-xiedong/.cache/packing
```

### 3.3 Packing 缓存文件结构

```
~/.cache/modelscope/tmp/<dataset_name>/
├── data.idx           # 索引文件 (pickle格式)
├── data-00000.bin     # 数据分片1 (pickle序列化)
├── data-00001.bin     # 数据分片2
├── data-00002.bin     # 数据分片3
└── ...
```

**索引文件内容 (data.idx):**
```python
{
    'idx': [0, 1024, 2048, ...],        # 每个样本的字节偏移量
    'length': [512, 1024, 768, ...],    # 每个样本的长度
    'n_shard': 3,                        # 分片数量
    'shard_offset': [0, 10GB, 20GB]     # 每个分片的起始偏移
}
```

**数据文件特点:**
- 使用 **mmap** (内存映射)读取,内存友好
- 每个分片最大 **10GB** (CHUNK_SIZE = 1e10)
- 数据用 pickle 序列化存储
- 支持随机访问

### 3.4 Packing 数据生成流程

```python
# 1. 读取预处理后的数据集
train_dataset = load_dataset(...)

# 2. 启用packing后,创建 PackingDataset
if args.packing:
    from swift.llm.dataset.utils import PackingDataset
    train_dataset = PackingDataset(
        template=template,
        dataset=train_dataset,
        packing_length=max_length,
        packing_num_proc=num_proc
    )

# 3. Packing过程:
#    - 按长度排序样本
#    - 贪心算法打包到packing_length
#    - 多进程加速

# 4. 写入IndexedDataset缓存
builder = IndexedDatasetBuilder(dataset_name)
builder.add_items(packed_samples)
builder.finalize()
```

### 3.5 Packing 缓存特性

**优点:**
- ✅ 高效随机访问 (mmap)
- ✅ 支持超大数据集 (分片存储)
- ✅ 内存占用小
- ✅ 多进程安全

**缓存复用条件:**
- 数据集名称相同
- packing_length 相同
- 原始数据未改变

---

## 4. 媒体资源缓存

### 4.1 缓存位置

```python
cache_dir = os.path.join(get_cache_dir(), 'media_resources')
# 实际: ~/.cache/modelscope/media_resources/
```

### 4.2 支持的媒体类型

- 图片: `images` 字段
- 视频: `videos` 字段  
- 音频: `audios` 字段

### 4.3 媒体路径处理

在你的 `dataset_info.json` 中:
```json
{
  "mmdu_val": {
    "file_name": "data.jsonl",
    "media_dir": "/mnt/jfs6/g-xiedong/mmdu_val/images"
  }
}
```

处理逻辑:
```python
# 如果jsonl中是相对路径
{"images": ["img1.jpg", "img2.jpg"]}

# 自动拼接为绝对路径
images = [
    "/mnt/jfs6/g-xiedong/mmdu_val/images/img1.jpg",
    "/mnt/jfs6/g-xiedong/mmdu_val/images/img2.jpg"
]
```

**注意:** 媒体文件本身不缓存,只有URL下载的资源会缓存。

---

## 5. 你的训练配置的缓存行为

### 5.1 当前配置分析

```yaml
# qwen3_vl_8b_train_swanlab.yaml
load_from_cache_file: true   # ✅ 启用数据预处理缓存
packing: true                 # ✅ 启用packing缓存
dataset_num_proc: 8           # 8进程并行处理
```

### 5.2 实际缓存目录

```bash
# 预处理缓存
/mnt/jfs6/g-xiedong/.cache/modelscope/datasets/map_cache/
  └── <fingerprint>.arrow  # 约几百MB到几GB

# Packing缓存 (如果使用Megatron packing)
/mnt/jfs6/g-xiedong/.cache/modelscope/tmp/mmdu_val/
  ├── data.idx
  └── data-00000.bin

# 媒体文件 (直接访问,不缓存)
/mnt/jfs6/g-xiedong/mmdu_val/images/
  └── *.jpg
```

### 5.3 首次训练流程

```
1. 读取 /mnt/jfs6/g-xiedong/mmdu_val/dataset_info.json
2. 加载 mmdu_val 数据集
3. 检查缓存: ~/.cache/modelscope/datasets/map_cache/<hash>.arrow
   - 不存在 → 执行预处理
     - 解析jsonl
     - 应用MessagesPreprocessor
     - 如果有mask_history_sample,拆分样本
     - 拼接media_dir路径
     - 写入.arrow缓存
4. 如果启用packing:
   - 检查 ~/.cache/modelscope/tmp/mmdu_val/data.idx
   - 不存在 → 执行packing
     - 计算样本长度
     - 贪心打包
     - 写入IndexedDataset
5. 训练使用缓存数据
```

### 5.4 后续训练流程

```
1. 检查预处理缓存 → 存在,直接加载
2. 检查packing缓存 → 存在,直接加载
3. 立即开始训练 (跳过所有预处理)
```

---

## 6. 缓存管理建议

### 6.1 清理缓存

```bash
# 清理所有数据缓存
rm -rf ~/.cache/modelscope/datasets/map_cache/*

# 清理packing缓存
rm -rf ~/.cache/modelscope/tmp/*

# 或设置环境变量后清理
rm -rf /mnt/jfs6/g-xiedong/.cache/modelscope/datasets/map_cache/*
```

### 6.2 何时需要清理缓存?

- ✅ 修改了 dataset_info.json 配置
- ✅ 修改了原始数据文件
- ✅ 修改了 mask_history_sample/max_human_steps 参数
- ✅ 升级了 ms-swift 版本
- ✅ 调试时想看最新的预处理结果

### 6.3 保留缓存的优势

- ⚡ 大幅加速训练启动 (跳过预处理)
- 💾 多次实验共享缓存
- 🔄 修改训练超参数(lr, batch_size等)不影响缓存复用

---

## 7. 与你的mask_history_sample功能的关系

### 7.1 数据处理流程

```
原始数据 (jsonl)
    ↓
预处理器 (MessagesPreprocessor)
    ↓ [mask_history_sample=true, max_human_steps=2]
样本拆分 (1个样本 → N个样本)
    ↓
写入Arrow缓存
    ↓ [load_from_cache_file=true]
从缓存加载 (已拆分的N个样本)
    ↓ [packing=true]
Packing (打包成更少的序列)
    ↓
写入IndexedDataset缓存
    ↓
训练
```

### 7.2 日志示例

根据我添加的日志,你会看到:

```
[数据集注册] 数据集 mmdu_val 启用了mask_history_sample功能
[数据集注册]   - mask_history_sample: True
[数据集注册]   - max_human_steps: 2

[数据集拆分] 预处理前数据集大小: 1000 个样本

[数据集拆分] 第一个样本拆分详情:
[数据集拆分]   原始对话轮数: 5 轮
[数据集拆分]   将拆分为: 5 个训练样本
[数据集拆分]   拆分样本 #1: 2条消息
[数据集拆分]   拆分样本 #2: 4条消息
[数据集拆分]   拆分样本 #3: 4条消息

[数据集拆分] 预处理后数据集大小: 5000 个样本
[数据集拆分] 样本数量变化: 1000 -> 5000 (扩增5.00x)

# 写入缓存: ~/.cache/modelscope/datasets/map_cache/abc123.arrow
# 包含5000个已拆分的样本

# 下次训练直接从缓存加载5000个样本
```

---

## 8. 常见问题

### Q1: 缓存占用空间太大怎么办?

```bash
# 查看缓存大小
du -sh ~/.cache/modelscope/datasets/map_cache/
du -sh ~/.cache/modelscope/tmp/

# 清理旧缓存
find ~/.cache/modelscope/datasets/map_cache/ -mtime +7 -delete
```

### Q2: 如何强制重新处理数据?

方法1: 修改配置
```yaml
load_from_cache_file: false
```

方法2: 删除缓存
```bash
rm -rf ~/.cache/modelscope/datasets/map_cache/*
```

### Q3: 多个实验共享缓存安全吗?

✅ 安全! 缓存基于数据指纹(fingerprint),不同配置会生成不同缓存文件。

### Q4: Packing缓存何时生效?

仅在启用 `packing: true` 且使用 Megatron 训练时生效。

### Q5: 缓存会自动更新吗?

❌ 不会。数据改变后需要手动清理缓存或设置 `load_from_cache_file: false`。

---

## 9. 总结

### 关键点

1. **数据预处理缓存** 在 `~/.cache/modelscope/datasets/map_cache/`
   - Arrow格式,快速加载
   - 基于fingerprint自动管理

2. **Packing缓存** 在 `~/.cache/modelscope/tmp/<dataset_name>/`
   - mmap高效访问
   - 仅Megatron+packing模式使用

3. **媒体文件** 直接访问,不缓存
   - 通过media_dir配置路径

4. **mask_history_sample拆分** 在预处理阶段完成
   - 拆分结果写入Arrow缓存
   - 后续训练直接使用缓存的拆分结果

### 最佳实践

- ✅ 生产训练: `load_from_cache_file: true` (加速启动)
- ✅ 调试数据: `load_from_cache_file: false` (实时看效果)
- ✅ 定期清理旧缓存
- ✅ 大数据集使用packing提高效率

---

**生成时间:** 2026-01-10  
**ms-swift 版本:** 最新  
**文档作者:** Claude (根据代码分析生成)

MS-SWIFT 数据缓存机制详解

# ms-swift SFT 训练数据格式指南

## 一、支持的4种数据格式

ms-swift 通过 `AutoPreprocessor` 自动识别以下格式：

### 1. Messages 格式（推荐）
```json
{
  "messages": [
    {"role": "system", "content": "你是助手"},
    {"role": "user", "content": "你好"},
    {"role": "assistant", "content": "你好！"}
  ]
}
```

### 2. ShareGPT 格式
```json
{
  "system": "你是助手",
  "conversation": [
    {"human": "你好", "assistant": "你好！"}
  ]
}
```

### 3. Query-Response 格式
```json
{
  "system": "你是助手",
  "query": "你好",
  "response": "你好！",
  "history": [["问题1", "回答1"]]
}
```

### 4. Alpaca 格式
```json
{
  "system": "你是助手",
  "instruction": "告诉我",
  "input": "天气",
  "output": "今天天气晴朗"
}
```

## 二、使用方式

```bash
# 直接传入文件路径，自动识别格式
swift sft --model qwen2.5-7b --dataset /path/to/data.jsonl

# 支持列名映射
swift sft --model qwen2.5-7b --dataset /path/to/data.jsonl --columns query:input response:output
```

---

## ms-swift vs LlamaFactory 对比

### 功能特性对比
```
┌──────────────────┬────────────────────────────────┬────────────────────────────┐
│       特性       │            ms-swift            │        LlamaFactory        │
├──────────────────┼────────────────────────────────┼────────────────────────────┤
│ 默认ShareGPT格式 │ conversation + human/assistant │ conversations + from/value │
├──────────────────┼────────────────────────────────┼────────────────────────────┤
│ 默认角色标签     │ human, assistant               │ human, gpt                 │
├──────────────────┼────────────────────────────────┼────────────────────────────┤
│ 默认消息字段     │ messages, conversation         │ conversations              │
├──────────────────┼────────────────────────────────┼────────────────────────────┤
│ 格式指定         │ 自动识别，无需指定             │ 需要formatting: sharegpt  │
└──────────────────┴────────────────────────────────┴────────────────────────────┘
```

### ShareGPT 格式对比

**LlamaFactory 的 ShareGPT 格式：**
```json
{
  "conversations": [
    {"from": "human", "value": "你好"},
    {"from": "gpt", "value": "你好！有什么可以帮助你的？"}
  ],
  "images": ["img.jpg"]
}
```

**ms-swift 的 ShareGPT 格式：**
```json
{
  "conversation": [
    {"human": "你好", "assistant": "你好！有什么可以帮助你的？"}
  ],
  "images": ["img.jpg"]
}
```

**ms-swift 的 Messages 格式（更通用）：**
```json
{
  "messages": [
    {"role": "user", "content": "你好"},
    {"role": "assistant", "content": "你好！有什么可以帮助你的？"}
  ],
  "images": ["img.jpg"]
}
```

## 关键差异总结
```
┌──────────────┬──────────────────────────────────┬─────────────────────────┐
│     方面     │             ms-swift             │      LlamaFactory       │
├──────────────┼──────────────────────────────────┼─────────────────────────┤
│ 消息字段名   │ messages 或 conversation         │ conversations           │
├──────────────┼──────────────────────────────────┼─────────────────────────┤
│ 角色字段     │ role 或嵌入key (human/assistant) │ from                    │
├──────────────┼──────────────────────────────────┼─────────────────────────┤
│ 内容字段     │ content 或嵌入value              │ value                   │
├──────────────┼──────────────────────────────────┼─────────────────────────┤
│ 助手角色名   │ assistant                        │ gpt                     │
├──────────────┼──────────────────────────────────┼─────────────────────────┤
│ 格式自动识别 │ 是                               │ 否，需配置              │
├──────────────┼──────────────────────────────────┼─────────────────────────┤
│ 数据注册     │ 可选（支持直接路径）             │ 需要dataset_info.json   │
├──────────────┼──────────────────────────────────┼─────────────────────────┤
│ loss控制     │ 支持"loss": true/false           │ 支持mask_history_sample │
└──────────────┴──────────────────────────────────┴─────────────────────────┘
```

## 互相转换

如果你有 LlamaFactory 格式的数据想在 ms-swift 中使用：

```bash
# ms-swift 可以直接处理，通过 tags 配置兼容
swift sft --model qwen2.5-7b --dataset /path/to/llamafactory_data.json
```

**ms-swift 的 `MessagesPreprocessor` 自动兼容：**
- `from` → `role`
- `value` → `content`
- `human/gpt` → `user/assistant`

**结论**：LlamaFactory 的 ShareGPT 数据可以直接用于 ms-swift，无需转换。

ms-swift SFT 训练数据格式

# Docker 镜像构建指南

## 📁 核心文件结构
```
/data/xiedong/modelscope/docker/
├── build_image.py           # 主构建脚本
├── Dockerfile.ubuntu        # 主 Dockerfile 模板
├── Dockerfile.extra_install # Python 和基础依赖安装
├── install.sh               # PyTorch/vLLM/FlashAttn 安装脚本
└── rcfiles/                 # 配置文件资源
```

## 🏗️ 构建类继承关系
```
Builder (基类)
  └── LLMImageBuilder
        └── SwiftImageBuilder (第347行) ← 当前使用的构建器
```

## ⚙️ SwiftImageBuilder 默认配置
位于 `build_image.py:349-364`
```python
base_image = 'nvidia/cuda:12.8.1-cudnn-devel-ubuntu22.04'
cuda_version = '12.8.1'
torch_version = '2.9.0'
vllm_version = '0.13.0'
lmdeploy_version = '0.10.1'
flashattn_version = '2.8.3'
```

## 🚀 构建命令

### 准备工作
```bash
cd /data/xiedong/modelscope
# 必须设置镜像仓库地址
export DOCKER_REGISTRY="你的镜像仓库地址"
```

### 方式1: 仅生成 Dockerfile (推荐先测试)
```bash
python docker/build_image.py \
    --image_type swift \
    --python_version 3.11.9 \
    --modelscope_version 1.33.0 \
    --swift_branch main \
    --dry_run 1
```
✅ 生成的 Dockerfile 在当前目录: `./Dockerfile`

### 方式2: 实际构建并推送
```bash
python docker/build_image.py \
    --image_type swift \
    --python_version 3.11.9 \
    --modelscope_version 1.33.0 \
    --swift_branch main \
    --dry_run 0
```

## 📊 可用参数列表

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `--image_type` | 镜像类型 | `swift` |
| `--python_version` | Python 版本 | `3.10.14` |
| `--ubuntu_version` | Ubuntu 版本 | `22.04` |
| `--torch_version` | PyTorch 版本 | `2.9.0` |
| `--cuda_version` | CUDA 版本 | `12.8.1` |
| `--vllm_version` | vLLM 版本 | `0.13.0` |
| `--flashattn_version` | FlashAttn 版本 | `2.8.3` |
| `--swift_branch` | ms-swift git 分支 | `main` |
| `--modelscope_branch` | modelscope git 分支 | `master` |
| `--modelscope_version` | 镜像 tag 中的版本号 | `9.99.0` |
| `--dry_run` | 1=只生成Dockerfile, 0=实际构建 | `0` |

## 🏷️ 生成的镜像名格式
```
{DOCKER_REGISTRY}:ubuntu22.04-cuda12.8.1-py311-torch2.9.0-1.33.0-swift-test
```

## 🔄 构建流程简述

### 1. **基础环境构建** (`Dockerfile.extra_install`)
- 从 NVIDIA CUDA 基础镜像开始
- 编译安装指定版本的 Python

### 2. **主构建流程** (`Dockerfile.ubuntu`)
- 安装 ms-swift (`pip install .[llm]`)
- 安装 modelscope
- 执行 `install.sh` 安装 PyTorch/vLLM/FlashAttn

### 3. **Swift 特有组件** (`Dockerfile.ubuntu:78-88`)
- 安装 Megatron-LM、apex、transformer_engine
- 克隆 Megatron-LM 到 `/root/.cache/modelscope/_github/`

## 🛠️ 手动构建流程 (灵活控制)

### 步骤1: 生成 Dockerfile
```bash
python docker/build_image.py --image_type swift --dry_run 1
```

### 步骤2: 查看/修改 Dockerfile
```bash
cat ./Dockerfile
# 按需修改 Dockerfile
```

### 步骤3: 手动构建镜像
```bash
docker build -t my-swift-image:latest -f Dockerfile .
```

### 步骤4: 推送镜像
```bash
docker push my-swift-image:latest
```

---

> 💡 **提示**: 建议先使用 `--dry_run 1` 参数测试生成 Dockerfile，确认无误后再进行实际构建。