https://code.claude.com/docs/zh-TW/overview

windows安装：
```bash
npm install -g @anthropic-ai/claude-code
```

安装：

```bash
curl -fsSL https://claude.ai/install.sh | bash
```

# Claude Code 配置指南

## 工作原理
Claude Code 是一个终端 AI 代理，具备以下能力：
- 文件操作：读取/修改文件
- 命令执行：执行 bash 命令
- 版本控制：管理 git
- 扩展功能：通过 MCP 协议连接外部工具
- 安全控制：使用分层权限系统控制操作

---

## 配置权限方法

### 方法一：全局配置（推荐）
编辑 `~/.claude/settings.json`：
```json
{
  "permissions": {
    "allow": [
      "Bash",
      "Edit",
      "Write",
      "WebFetch",
      "WebSearch"
    ],
    "defaultMode": "acceptEdits"
  }
}
```

### 方法二：项目级配置
编辑 `/data/xiedong/LlamaFactory/.claude/settings.local.json`：
```json
{
  "permissions": {
    "allow": [
      "Bash",
      "Edit",
      "Write"
    ],
    "deny": [
      "Bash(rm -rf:*)",
      "Bash(sudo:*)"
    ],
    "defaultMode": "acceptEdits"
  }
}
```

### 方法三：完全跳过权限（最激进）
```json
{
  "permissions": {
    "defaultMode": "bypassPermissions"
  }
}
```

---

## 配置文件优先级
配置文件按以下优先级生效（从高到低）：
1. **项目级本地配置**：`.claude/settings.local.json`
2. **项目级配置**：`.claude/settings.json`
3. **全局配置**：`~/.claude/settings.json`

---

## 查看当前权限
在 Claude Code 会话中，输入以下命令查看当前生效的权限规则：
```
/permissions
```

# Claude Code 命令速查表

## 📋 核心命令

| 命令 | 功能说明 |
|------|----------|
| `/help` | 显示帮助信息 |
| `/clear` | 清除对话历史，重新开始 |
| `/compact` | 压缩上下文，减少 token 使用 |
| `/config` | 查看或修改配置 |
| `/cost` | 显示当前会话的 token 使用和费用 |
| `/doctor` | 检查环境与配置问题 |
| `/init` | 初始化当前目录的 CLAUDE.md 项目文件 |
| `/login` | 切换账号或重新登录 |
| `/logout` | 登出当前账号 |
| `/memory` | 编辑 CLAUDE.md 记忆文件 |
| `/model` | 切换模型 (sonnet/opus/haiku) |
| `/permissions` | 查看或修改工具权限 |
| `/pr-comments` | 查看 PR 评论 |
| `/review` | 代码审查 |
| `/status` | 显示当前状态（模型、目录等） |
| `/terminal-setup` | 设置终端集成功能 |
| `/vim` | 切换 vim 编辑模式 |
| `/tasks` | 显示后台运行的任务 |

## ⌨️ 快捷键

| 快捷键 | 功能 |
|--------|------|
| `Ctrl+C` | 中断当前操作或退出 |
| `Escape` (连按两次) | 中断当前操作 |
| `Shift+Enter` | 输入多行内容（需先运行 `/terminal-setup`） |

## 💡 使用提示
- 输入 `/help` 可查看完整的最新命令列表
- 建议先运行 `/terminal-setup` 以获得最佳编辑体验
- 使用 `/model` 可根据需求切换不同性能的模型


## 工作原理

  7阶段特性开发流程（feature-dev 插件）:
  1. 发现 → 理解需求
  2. 探索 → 并行启动多个代理搜索相关代码
  3. 澄清 → 向用户提问不明确的地方
  4. 设计 → 生成多个架构方案供选择
  5. 实现 → 获得批准后执行
  6. 审查 → 并行启动审查代理检查质量
  7. 总结 → 汇报完成情况


Claude Code 使用

# 分布式训练配置方案
针对您的场景（**普通Qwen3-VL 8B，4机32卡**），我给出最优配置方案：

## 一、硬件拓扑分析
- **节点数量**：4台机器
- **单机配置**：8卡/机
- **总计GPU**：32卡
- **节点内带宽**：NVLink/NVSwitch (900 GB/s)
- **节点间带宽**：InfiniBand/RoCE (200-400 Gb/s)
- **核心原则**：TP在节点内，PP/DP可跨节点



## 二、推荐配置方案

### 🏆 方案1：TP=4, PP=1, DP=8（最推荐）

**核心配置**：
```yaml
# 基础配置
model_name_or_path: Qwen/Qwen3-VL-8B-Instruct
do_train: true
stage: sft
finetuning_type: full
freeze_vision_tower: false
freeze_multi_modal_projector: false
freeze_language_model: false

# 数据设置
dataset: your_dataset
template: qwen3_vl
cutoff_len: 4096
image_max_pixels: 451584

# 训练参数
output_dir: saves/qwen3_vl_8b_32gpu
per_device_train_batch_size: 1
gradient_accumulation_steps: 8
num_train_epochs: 3
learning_rate: 2e-5
lr_scheduler_type: cosine
bf16: true
logging_steps: 5
save_steps: 200

# Megatron并行配置
tensor_model_parallel_size: 4 # 4卡TP（节点内）
pipeline_model_parallel_size: 1 # 不用PP
sequence_parallel: false

# 性能优化
bias_activation_fusion: true
apply_rope_fusion: true
use_distributed_optimizer: true
overlap_param_gather: true
overlap_grad_reduce: true
```

**并行拓扑**：
```
数据并行 (DP) = 32 / (4 * 1) = 8 路
- 每个节点2个DP组（8卡/节点 ÷ 4卡TP = 2组）
- 8个DP组分布在4台机器上

张量并行 (TP) = 4
- 每4卡一组，共享模型权重切片
- 在节点内或跨2个节点

全局Batch Size = 8 (DP) × 1 (bs) × 8 (acc) = 64
```

**优势**：
✅ TP=4足够放下8B模型单层的切片
✅ DP=8提供充足的并行度
✅ 避免PP的bubble损失（PP效率通常85-90%）
✅ 跨节点只有DP梯度同步，可与计算重叠

---

### 🥈 方案2：TP=8, PP=1, DP=4（显存更宽裕）

```yaml
# 与方案1不同之处
per_device_train_batch_size: 2 # TP=8显存更多，可增大bs
gradient_accumulation_steps: 8
tensor_model_parallel_size: 8 # 整机8卡做TP
pipeline_model_parallel_size: 1
sequence_parallel: true # TP=8建议开启
```

**并行拓扑**：
```
DP = 32 / 8 = 4 (每机一组TP，4机=4个DP组)
TP = 8 (单机8卡，充分利用NVLink)
全局Batch Size = 4 × 2 × 8 = 64
```

**优势**：
✅ TP=8在单节点内，通信最快
✅ 每卡显存占用最小（模型切成8份）
✅ 可以增大per_device_batch_size到2
⚠️ DP=4并行度较低，但batch size可补偿

---

### 🥉 方案3：TP=2, PP=2, DP=8（平衡方案）

```yaml
# 与方案1不同之处
per_device_train_batch_size: 1
gradient_accumulation_steps: 8
tensor_model_parallel_size: 2 # 最小TP
pipeline_model_parallel_size: 2 # 2段流水线
sequence_parallel: false

# PP专用参数
virtual_pipeline_model_parallel_size: 2 # 虚拟流水线减少bubble
```

**并行拓扑**：
```
DP = 32 / (2 * 2) = 8
TP = 2 (每2卡一组)
PP = 2 (模型分2段)
每个节点：8卡 / 2(TP) = 4组，每组再分2段PP
```

**优势**：
✅ DP=8高并行度
✅ TP=2通信开销小
⚠️ PP=2引入10-15% bubble loss
⚠️ 配置较复杂

---

## 三、关键参数调优建议

### 1. sequence_parallel 设置
```yaml
# 当 TP >= 4 时开启，可节省激活内存
tensor_model_parallel_size: 4
sequence_parallel: true # 沿序列维度并行，降低激活显存

# TP < 4 时不建议开启
tensor_model_parallel_size: 2
sequence_parallel: false
```

### 2. recompute_granularity 设置
```bash
# 估算Qwen3-VL 8B显存占用
python3 -c "
model_params = 8e9 # 8B参数
bytes_per_param = 2 # bf16

# 模型权重
model_memory = model_params * bytes_per_param / 1e9 # GB

# 优化器状态 (Adam: 8 bytes/param for fp32 momentum+variance)
optimizer_memory = model_params * 8 / 1e9

# 梯度
gradient_memory = model_params * bytes_per_param / 1e9

# 激活（粗略估计）
activation_memory_per_layer = 0.5 # GB
num_layers = 32
activation_memory = activation_memory_per_layer * num_layers

print(f'=== Qwen3-VL 8B 单卡显存估算 (不考虑并行) ===')
print(f'模型权重: {model_memory:.1f} GB')
print(f'优化器状态: {optimizer_memory:.1f} GB') 
print(f'梯度: {gradient_memory:.1f} GB')
print(f'激活内存: {activation_memory:.1f} GB (bs=1, len=4096)')
print(f'总计: {model_memory + optimizer_memory + gradient_memory + activation_memory:.1f} GB')
print()

# TP=4时的显存
print(f'=== TP=4, 分布式优化器时的单卡显存 ===')
tp = 4
print(f'模型权重: {model_memory/tp:.1f} GB')
print(f'优化器状态: {optimizer_memory/tp:.1f} GB (分布式优化器)')
print(f'梯度: {gradient_memory/tp:.1f} GB')
print(f'激活内存: {activation_memory:.1f} GB (激活不切分)')
print(f'总计: {(model_memory + optimizer_memory + gradient_memory)/tp + activation_memory:.1f} GB')
"
```

**显存估算结果**：
```
=== Qwen3-VL 8B 单卡显存估算 (不考虑并行) ===
模型权重: 16.0 GB
优化器状态: 64.0 GB
梯度: 16.0 GB
激活内存: 16.0 GB (bs=1, len=4096)
总计: 112.0 GB

=== TP=4, 分布式优化器时的单卡显存 ===
模型权重: 4.0 GB
优化器状态: 16.0 GB (分布式优化器)
梯度: 4.0 GB
激活内存: 16.0 GB (激活不切分)
总计: 40.0 GB
```

**根据GPU型号选择**：
```yaml
# A100/H100 80GB：显存充足
recompute_granularity: null # 或不设置
# 预计显存: ~40GB (TP=4) 或 ~45GB (TP=8)

# A100 40GB：显存紧张
recompute_granularity: selective # 节省约30%激活内存
# 预计显存: ~30GB (TP=4)

# V100 32GB：显存非常紧张 
recompute_granularity: full # 节省约50%激活内存
per_device_train_batch_size: 1 # 且必须bs=1
# 预计显存: ~25GB (TP=4)
```

### 3. gradient_accumulation_steps 调优
```yaml
# 目标：全局batch size = 64-128 (经验值)

# TP=4, DP=8
gradient_accumulation_steps: 8 # 全局bs = 8*1*8 = 64
# 或
gradient_accumulation_steps: 16 # 全局bs = 8*1*16 = 128

# TP=8, DP=4 
gradient_accumulation_steps: 8 # 全局bs = 4*2*8 = 64
per_device_train_batch_size: 2 # TP=8显存更多
```

---

## 四、完整推荐配置（TP=4方案）

```yaml
# === 模型和数据 ===
model_name_or_path: Qwen/Qwen3-VL-8B-Instruct
dataset_dir: /path/to/your/data
dataset: your_dataset
template: qwen3_vl
cutoff_len: 4096
image_max_pixels: 451584
video_max_pixels: 16384
trust_remote_code: true

# === 训练配置 ===
do_train: true
stage: sft
finetuning_type: full

# 多模态部位训练控制
freeze_vision_tower: false # 训练视觉编码器
freeze_multi_modal_projector: false # 训练投影层
freeze_language_model: false # 训练语言模型

# === 超参数 ===
output_dir: saves/qwen3_vl_8b_4m32g
per_device_train_batch_size: 1 # 单卡batch
gradient_accumulation_steps: 8 # 累积步数
num_train_epochs: 3
learning_rate: 2e-5
lr_scheduler_type: cosine
warmup_ratio: 0.03
weight_decay: 0.01
bf16: true

# === 日志和保存 ===
logging_steps: 5
save_steps: 200
save_strategy: steps
save_total_limit: 3
evaluation_strategy: no # 或 steps
load_best_model_at_end: false
report_to: tensorboard

# === 数据加载 ===
preprocessing_num_workers: 16 # 4机32卡，多进程预处理
dataloader_num_workers: 4
dataloader_pin_memory: true
remove_unused_columns: false

# === 分布式配置 ===
ddp_timeout: 180000000 # 跨节点超时时间
ddp_find_unused_parameters: false

# ===== Megatron-Core并行配置 =====
# DP=8, TP=4, PP=1, 总计32卡
tensor_model_parallel_size: 4 # 4路张量并行
pipeline_model_parallel_size: 1 # 不用流水线并行
sequence_parallel: false # 4096长度下不需要

# === Megatron性能优化 ===
bias_activation_fusion: true # 融合bias和激活
apply_rope_fusion: true # 融合RoPE计算
use_distributed_optimizer: true # 分布式优化器（必须）
overlap_param_gather: true # 参数预取（重要）
overlap_grad_reduce: true # 梯度异步规约（重要）

# === 显存优化（根据GPU型号选择）===
# A100/H100 80GB: 不需要recompute
# recompute_granularity: null

# A100 40GB: 使用selective
# recompute_granularity: selective

# V100 32GB: 使用full
# recompute_granularity: full
# per_device_train_batch_size: 1
```

---

## 五、启动命令

### 1. 设置环境变量
```bash
export USE_MCA=1
export CUDA_DEVICE_MAX_CONNECTIONS=1 # Megatron推荐
export NCCL_IB_DISABLE=0 # 启用InfiniBand
export NCCL_NET_GDR_LEVEL=5 # GPU Direct RDMA
export NCCL_SOCKET_IFNAME=eth0 # 根据实际网卡名修改
```

### 2. 分布式启动
```bash
# 在主节点执行（node_rank=0）：
torchrun \
 --nproc_per_node=8 \
 --nnodes=4 \
 --node_rank=0 \
 --master_addr="主节点IP" \
 --master_port=29500 \
 $(which llamafactory-cli) train examples/megatron/qwen3_vl_32gpu.yaml

# 在其他3个节点分别执行：
# 节点1：node_rank=1
# 节点2：node_rank=2 
# 节点3：node_rank=3
torchrun \
 --nproc_per_node=8 \
 --nnodes=4 \
 --node_rank=1 \
 --master_addr="主节点IP" \
 --master_port=29500 \
 $(which llamafactory-cli) train examples/megatron/qwen3_vl_32gpu.yaml
```

---

## 六、性能预期

### TP=4, DP=8配置：
- **预计吞吐**：3000-4000 tokens/s/GPU
- **训练时间**（10万样本）：约2-3小时
- **显存占用**：40GB/GPU (A100 80GB充足)
- **对比单机8卡**：
 - 4倍数据并行加速（理想情况）
 - 实际加速比：3.2-3.6x（考虑跨节点通信）

---

## 七、故障排查

### 1. 如果遇到OOM（显存不足）：
- 减小 `per_device_train_batch_size` 到 1
- 启用 `recompute_granularity: selective`
- 增大 `tensor_model_parallel_size` 到 8
- 减小 `cutoff_len` 到 2048

### 2. 如果速度慢：
- 检查 `overlap_param_gather` 和 `overlap_grad_reduce` 是否为 true
- 检查跨节点网络带宽（iperf3测试）
- 启用 `NCCL_DEBUG=INFO` 查看通信瓶颈

LLaMAFactory Megatron的加速（4）4机32卡配置

# LlamaFactory 中 Megatron 启动原理和超参数详解

根据代码分析，我为您详细解答这些问题。

## 1. Megatron 的启动原理

在 LlamaFactory 中，Megatron 通过 MCA (Megatron Core Adapter) 集成。

**启动流程如下：**

**核心文件：**
* `src/train.py` → `src/llamafactory/train/tuner.py`
* `src/llamafactory/train/mca/workflow.py`

**启动机制：**

```bash
USE_MCA=1 llamafactory-cli train examples/megatron/qwen3_moe_full.yaml
```

**代码路径 (`tuner.py:69-83`)：**

```python
if finetuning_args.stage in ["pt", "sft", "dpo"] and finetuning_args.use_mca:
 if not is_mcore_adapter_available():
 raise ImportError("mcore_adapter is not installed...")
 if finetuning_args.stage == "sft":
 from .mca import run_sft as run_sft_mca
 run_sft_mca(model_args, data_args, training_args, finetuning_args, callbacks)
```

**当设置 `USE_MCA=1` 时，系统会：**
* 使用 `mcore_adapter.models.AutoModel.from_pretrained()` 加载模型（而非 HF 的 AutoModel）
* 使用 `McaTrainer` 替代标准的 Trainer
* 启用 Megatron-Core 的并行化机制

## 2. Megatron 对三个部位训练的支持

✅ **完全支持！** 在 `workflow.py:164-179` 中实现了针对 Qwen2-VL / Qwen3-VL 的冻结逻辑：

```python
if getattr(model.config, "hf_model_type", None) in ["qwen2_vl", "qwen2_5_vl", "qwen3_vl"]:
 params_to_freeze = []
 if finetuning_args.freeze_vision_tower:
 params_to_freeze.extend(["vision_model.blocks", "vision_model.patch_embed"])
 if finetuning_args.freeze_multi_modal_projector:
 params_to_freeze.extend(["multi_modal_projector"])
 if finetuning_args.freeze_language_model:
 params_to_freeze.extend(["embedding", "decoder", "output_layer"])
 if params_to_freeze:
 for name, p in model.named_parameters():
 if any(name.startswith(k) for k in params_to_freeze):
 p.requires_grad_(False)
```

**您的配置完全有效：**

```yaml
freeze_vision_tower: false # 训练视觉编码器
freeze_multi_modal_projector: false # 训练投影层
freeze_language_model: false # 训练语言模型
```

## 3. 基础 Megatron 超参数详解

| 参数 | 设置 | 含义与说明 |
| :--- | :--- | :--- |
| **tensor_model_parallel_size** | `1` | **张量并行度**（在单个 Transformer 层内部切分权重矩阵） **原理**：将每个注意力头、FFN 等矩阵按列或行切分到多个 GPU。 **如何设置**： • 单机多卡（同一节点内高速互联）：2/4/8（需是 GPU 数的因子） • 跨节点：不建议使用，通信开销大 **您的场景**：1（不使用 TP）是合理的 |
| **pipeline_model_parallel_size** | `1` | **流水线并行度**（按层切分模型） **原理**：将模型的层分成 N 段，分配到 N 个 GPU，形成流水线。 **如何设置**： • 计算公式：`PP * TP * DP = 总GPU数` • 推荐值：2/4/8（层数必须能被 PP 整除） **您的场景**：1（不使用 PP） |
| **sequence_parallel** | `false` | **序列并行**（沿序列长度维度并行） **前提**：必须启用 `tensor_model_parallel_size > 1`。 **作用**：减少激活内存占用。 **您的场景**：false（因为 TP=1） |
| **bias_activation_fusion** | `true` | **融合 bias 加法和激活函数操作** **效果**：减少 kernel 启动次数，提升约 5-10% 速度。 **建议**：始终设为 true。 |
| **apply_rope_fusion** | `true` | **融合 RoPE 位置编码计算** **效果**：优化位置编码的计算效率。 **建议**：始终设为 true。 |
| **use_distributed_optimizer** | `true` | **分布式优化器状态** **原理**：将优化器状态（如 Adam 的 momentum）分片存储。 **效果**：显著降低显存占用（约 33% 优化器内存）。 **建议**：多卡训练时必须 true。 |

## 4. MoE 模型额外超参数详解

您的 MoE 配置新增了 5 个参数：

| 参数 | 设置 | 含义与说明 |
| :--- | :--- | :--- |
| **overlap_param_gather** | `true` | **参数收集与计算重叠** **原理**：在 DDP/FSDP 中，提前开始下一层的参数 all-gather。 **效果**：隐藏通信延迟，提升 10-15% 吞吐。 **建议**：始终 true。 |
| **overlap_grad_reduce** | `true` | **梯度规约与反向传播重叠** **原理**：边计算梯度边进行 all-reduce 通信。 **效果**：隐藏通信延迟。 **建议**：始终 true。 |
| **moe_grouped_gemm** | `true` | **MoE 专家使用分组矩阵乘法** **原理**：将多个专家的 GEMM 操作合并成一次调用。 **效果**：大幅提升 MoE 计算效率（30-50%）。 **建议**：MoE 模型必须 true。 |
| **moe_token_dispatcher_type** | `alltoall` | **Token 分发到专家的通信策略** **可选值**： • `alltoall`: All-to-All 通信（标准方式） • `allgather`: All-Gather 通信（备选） **如何选择**： • 专家并行 > 1：使用 `alltoall`（您的场景） • 专家并行 = 1：使用 `allgather` |
| **expert_model_parallel_size** | `2` | **专家并行度**（将 64 个专家分配到 2 个 GPU 组） **原理**：每个 GPU 组负责 32 个专家。 **约束**：`EP * TP * PP <= 总GPU数` **如何设置**： • 专家数多：设为 2/4/8 **您的场景（Qwen3-30B-A3B，3 个激活专家）**： `expert_model_parallel_size: 2` 是合理的。 总并行：EP(2) * PP(4) = 8 GPUs |
| **recompute_granularity** | `full` | **重计算粒度**（牺牲速度换显存） **可选值**： • `null`: 不重计算 • `selective`: 选择性重计算（如激活函数） • `full`: 完整重计算整个 Transformer 块 **效果**：full 可节省 50% 激活内存，但慢 20-30%。 **建议**： • 显存充足：`null` 或 `selective` • 显存不足：`full` |

## 推荐配置策略

**8 卡场景（您的 MoE 配置）：**

```yaml
# 全局批次大小 = (8 GPU / EP(2) / PP(4)) * bs(1) * acc(8) = 8
tensor_model_parallel_size: 1 # 不用TP，避免通信开销
pipeline_model_parallel_size: 4 # 4段流水线
expert_model_parallel_size: 2 # 专家分2组
# 数据并行度自动 = 8 / (1 * 4 * 2) = 1

sequence_parallel: false # TP=1时必须false
bias_activation_fusion: true # 必开
apply_rope_fusion: true # 必开
use_distributed_optimizer: true # 必开
overlap_param_gather: true # 必开
overlap_grad_reduce: true # 必开
moe_grouped_gemm: true # MoE必开
moe_token_dispatcher_type: alltoall # EP>1时用alltoall
recompute_granularity: full # 显存紧张时用full
```

**如果只有 4 卡：**

```yaml
tensor_model_parallel_size: 1
pipeline_model_parallel_size: 2 # 改为2
expert_model_parallel_size: 2 # 保持2
# 其他参数不变
```

**如果显存充足（如 H100 80GB）：**

```yaml
recompute_granularity: selective # 改为selective提速
pipeline_model_parallel_size: 2 # 减少PP提速
```

---

**参考资料：**
* GitHub - https://github.com/NVIDIA/Megatron-LM
* Parallelisms — https://docs.nvidia.com/nemo-framework/user-guide/latest/parallelism/index.html
* Parallelisms Guide — https://github.com/NVIDIA/Megatron-Bridge
* Efficient Large-Scale Language Model Training on GPU Clusters Using Megatron-LM

LLaMAFactory Megatron的加速（3）参数解释

```bash
sudo apt-get install -y jq
```

```bash
# 更清晰的统计
docker image inspect kevinchina/deeplearning:llamafactory0-9-4-base-1-megatron-1-ok-tars1 | jq -r '.[0].RootFS.Layers | length'
```

如何查看镜像有多少层？

# 使用 Hugging Face API 操作仓库指南

## 简介

本文介绍如何使用 Hugging Face API 通过 Python 直接操作 Hugging Face 仓库（模型或数据集），包括上传、删除、列出文件等常见操作。这种方法比使用命令行工具更灵活，特别适合批量操作和自动化脚本。



## 前置准备

### 1. 安装依赖

```bash
pip install -U "huggingface_hub[cli]" --break-system-packages
```

### 2. 获取 API Token

1. 登录 [Hugging Face 官网](https://huggingface.co)
2. 点击头像 → Settings → Access Tokens
3. 创建新 Token（需勾选 **write** 权限）

### 3. 设置环境变量

```bash
export HF_TOKEN='你的Token'
```

## 基本操作

### 初始化 API 客户端

```python
import sys
sys.path.insert(0, '/home/xd/.local/lib/python3.12/site-packages') # 如果包安装在用户目录
from huggingface_hub import HfApi
import os

# 方式1: 从环境变量读取
api = HfApi(token=os.environ.get('HF_TOKEN'))

# 方式2: 直接指定（不推荐，安全性差）
api = HfApi(token='hf_xxxxxxxxxxxxx')
```

## 常用操作示例

### 1. 上传整个文件夹

```python
cd /data/xiedong/mmdu/mmdu_val && export HF_TOKEN=xxxx && python -c "
import sys
sys.path.insert(0, '/home/xd/.local/lib/python3.12/site-packages')
from huggingface_hub import HfApi
import os

api = HfApi(token=os.environ.get('HF_TOKEN', 'xxxx'))

# 上传整个文件夹
api.upload_folder(
 folder_path='.', # 当前目录
 repo_id='hugxd/mmdu_val', # 仓库ID: 用户名/仓库名
 repo_type='dataset', # 'model' 或 'dataset'
 ignore_patterns=['.git/**'] # 忽略的文件模式
)
"
```

**参数说明：**
- `folder_path`: 要上传的本地文件夹路径
- `repo_id`: 仓库ID，格式为 `用户名/仓库名`
- `repo_type`: 仓库类型，`'model'` 或 `'dataset'`
- `ignore_patterns`: 要忽略的文件模式列表

### 2. 删除文件

```python
cd /data/xiedong/mmdu/mmdu_val && export HF_TOKEN=xxxx && python -c "
import sys
sys.path.insert(0, '/home/xd/.local/lib/python3.12/site-packages')
from huggingface_hub import HfApi
import os

api = HfApi(token=os.environ.get('HF_TOKEN', 'xxxx'))

# 要删除的文件列表
files_to_delete = [
 'benchmark.json',
 'mmdu-45k.json',
 'mmdu-45k_pics.zip',
 'mmdu_pics.zip'
]

print('开始删除无关文件...')
for file in files_to_delete:
 try:
 api.delete_file(
 path_in_repo=file,
 repo_id='hugxd/mmdu_val',
 repo_type='dataset'
 )
 print(f'✓ 已删除: {file}')
 except Exception as e:
 print(f'✗ 删除失败 {file}: {e}')

print('\\n删除完成！')
"
```

### 3. 列出仓库文件

```python
cd /data/xiedong/mmdu/mmdu_val && export HF_TOKEN=xxxx && python -c "
import sys
sys.path.insert(0, '/home/xd/.local/lib/python3.12/site-packages')
from huggingface_hub import HfApi
import os

api = HfApi(token=os.environ.get('HF_TOKEN', 'xxxx'))

# 列出所有文件
files = api.list_repo_files('hugxd/mmdu_val', repo_type='dataset')

print(f'仓库中共有 {len(files)} 个文件:')
for f in sorted(files):
 print(f)
"
```

### 4. 上传单个文件

```python
api.upload_file(
 path_or_fileobj='/path/to/local/file.json',
 path_in_repo='file.json', # 在仓库中的路径
 repo_id='hugxd/mmdu_val',
 repo_type='dataset'
)
```

### 5. 创建仓库（如果不存在）

```python
api.create_repo(
 repo_id='hugxd/mmdu_val',
 repo_type='dataset',
 exist_ok=True # 如果已存在则不会报错
)
```

## 完整示例：同步本地文件夹到远程仓库

```bash
cd /path/to/local/folder && export HF_TOKEN=你的Token && python -c "
import sys
sys.path.insert(0, '/home/xd/.local/lib/python3.12/site-packages')
from huggingface_hub import HfApi
import os

api = HfApi(token=os.environ.get('HF_TOKEN'))

# 1. 创建仓库（如果不存在）
api.create_repo(
 repo_id='用户名/仓库名',
 repo_type='dataset', # 或 'model'
 exist_ok=True
)

# 2. 上传整个文件夹
api.upload_folder(
 folder_path='.',
 repo_id='用户名/仓库名',
 repo_type='dataset',
 ignore_patterns=['.git/**', '__pycache__/**', '*.pyc']
)

print('上传完成！')
"
```

## 提示词模板（给 AI 使用）

当需要操作 Hugging Face 仓库时，可以使用以下提示词模板：

```
请使用 Hugging Face API 帮我操作仓库：

仓库信息：
- 仓库ID: hugxd/mmdu_val
- 仓库类型: dataset (或 model)
- API Token: xxxx

操作需求：
1. [具体操作，如：上传本地文件夹 /data/xiedong/mmdu/mmdu_val]
2. [或：删除文件 benchmark.json, mmdu-45k.json]
3. [或：列出所有文件]

请使用以下格式的命令：
cd [工作目录] && export HF_TOKEN=[Token] && python -c "
import sys
sys.path.insert(0, '/home/xd/.local/lib/python3.12/site-packages')
from huggingface_hub import HfApi
import os

api = HfApi(token=os.environ.get('HF_TOKEN', '[Token]'))

# [具体操作代码]
"
```

## 注意事项

1. **安全性**: 不要在代码中硬编码 API Token，优先使用环境变量
2. **权限**: 确保 Token 有 write 权限才能上传/删除文件
3. **路径**: `path_in_repo` 是文件在仓库中的相对路径，不是本地路径
4. **仓库类型**: 区分 `'model'` 和 `'dataset'`，操作时需指定正确类型
5. **批量操作**: 删除多个文件时，建议使用循环并添加异常处理

## 常见问题

### Q: 上传大文件时超时怎么办？
A: 使用 `upload_large_folder` 方法，或分批上传：

```python
api.upload_large_folder(
 folder_path='.',
 repo_id='hugxd/mmdu_val',
 repo_type='dataset'
)
```

### Q: 如何只上传特定文件？
A: 使用 `ignore_patterns` 参数排除不需要的文件，或使用 `upload_file` 逐个上传。

### Q: 如何检查文件是否已存在？
A: 先使用 `list_repo_files` 列出所有文件，然后检查目标文件是否在列表中。

## 参考文档

- [Hugging Face Hub 官方文档](https://huggingface.co/docs/huggingface_hub)
- [API 参考](https://huggingface.co/docs/huggingface_hub/v0.20.0/en/package_reference/hf_api)

使用 Hugging Face API 操作仓库指南

多模态多轮对话数据集

LLamaFactory

## 本地示例数据集（可直接使用）

在 `data` 目录下有以下测试数据集：

1. **`mllm_demo`** - 多模态图像数据集
   - 文件：`data/mllm_demo.json`
   - 包含图像和对话数据
   - 支持中英文

2. **`mllm_video_demo`** - 多模态视频数据集
   - 文件：`data/mllm_video_demo.json`
   - 包含视频和对话数据

3. **`mllm_audio_demo`** - 多模态音频数据集
   - 文件：`data/mllm_audio_demo.json`
   - 包含音频和对话数据

4. **`mllm_video_audio_demo`** - 视频+音频混合数据集
   - 文件：`data/mllm_video_audio_demo.json`
   - 同时包含视频和音频

这些数据集已配置在 `dataset_info.json` 中，可直接使用。

## 在线数据集（从 HuggingFace 下载）

在 `dataset_info.json` 中还配置了以下在线数据集：

- **`llava_1k_en`** / **`llava_1k_zh`** - LLaVA 数据集（1k 样本，英文/中文）
- **`llava_150k_en`** / **`llava_150k_zh`** - LLaVA 数据集（150k 样本）
- **`pokemon_cap`** - Pokemon 图像描述数据集
- **`mllm_pt_demo`** - 多模态预训练演示数据集
- **`rlhf_v`** - 视觉反馈数据集（用于 DPO 训练）
- **`vlfeedback`** - 视觉反馈数据集
- **`rlaif_v`** - RLAIF-V 数据集

## 使用方法

训练时指定数据集名称，例如：

```bash
llamafactory-cli train --dataset mllm_demo
```

或使用多个数据集：

```bash
llamafactory-cli train --dataset mllm_demo,mllm_video_demo
```

这些数据集已配置好，可直接用于测试多模态训练功能。

用于训练框架测试的小型多模态数据集

单机4卡训练 LLaMAFactory Megatron 速度如何？这篇做了测试。

## MCA 训练

镜像`kevinchina/deeplearning:llamafactory0-9-4-base-1-megatron-1-ok`

单机4卡训练。

脚本：

```bash
model_name_or_path: /mnt/jfs6/model/Qwen3-VL-8B-Instruct/
image_max_pixels: 451584
video_max_pixels: 16384

do_train: true
stage: sft
finetuning_type: full
dataset: llava_1k_en  # 或使用 mllm_demo
template: qwen3_vl_nothink
cutoff_len: 2048
trust_remote_code: true

output_dir: saves/mca/qwen3_vl_test2
per_device_train_batch_size: 1
gradient_accumulation_steps: 8
num_train_epochs: 1.0
learning_rate: 1.0e-6
lr_scheduler_type: cosine
bf16: true
flash_attn: auto

# 冻结参数配置
freeze_vision_tower: false
freeze_multi_modal_projector: false
freeze_language_model: false

# 数据加载配置
preprocessing_num_workers: 32
preprocessing_batch_size: 32
dataloader_num_workers: 32
data_shared_file_system: true

# 日志和保存配置
logging_steps: 10
plot_loss: true
save_steps: 500
save_strategy: steps
overwrite_output_dir: false
save_only_model: false
report_to: none

# SwanLab 配置
use_swanlab: true
swanlab_project: run-qwen3vl8b-1030  # 可根据需要修改
swanlab_mode: cloud
# swanlab_api_key: pM7Xvs5OS2EeXPO5gKXfJ  # 建议通过环境变量设置，不要硬编码在配置文件中

# Megatron 并行配置
tensor_model_parallel_size: 1
pipeline_model_parallel_size: 4
sequence_parallel: false
bias_activation_fusion: true
apply_rope_fusion: true
use_distributed_optimizer: true
```

训练指令：

```bash
USE_MCA=1 llamafactory-cli train /mnt/s3fs/train-LlamaFactory/examples/megatron/qwen3_vl_2b_full.yaml
```

qwen3vl 8b MCA用时：3分钟37秒

显存占用：


![image.png](/static/img/27fbc2a89bc376978bd49d24258a6f7f.image.webp)


数据缓存：
```bash
# 或者清除所有缓存（如果上面不行）
rm -rf ~/.cache/huggingface/datasets/*
```

## deepspeed

镜像：kevinchina/deeplearning:llamafactory0-9-4-base-1-megatron-1-ok 不行了，deepspeed版本不对。

使用镜像`kevinchina/deeplearning:llamafactory-qwen3vl-ok`


```bash
model_name_or_path: /mnt/jfs6/model/Qwen3-VL-8B-Instruct/
image_max_pixels: 451584
video_max_pixels: 16384

do_train: true
stage: sft
finetuning_type: full
dataset: llava_1k_en  # 或使用 mllm_demo
template: qwen3_vl_nothink
cutoff_len: 2048
trust_remote_code: true

output_dir: saves/mca/qwen3_vl_haha1
per_device_train_batch_size: 1
gradient_accumulation_steps: 8
num_train_epochs: 1.0
learning_rate: 1.0e-6
lr_scheduler_type: cosine
bf16: true
flash_attn: auto

# 冻结参数配置
freeze_vision_tower: false
freeze_multi_modal_projector: false
freeze_language_model: false

# 数据加载配置
preprocessing_num_workers: 32
preprocessing_batch_size: 32
dataloader_num_workers: 32
data_shared_file_system: true

# 日志和保存配置
logging_steps: 10
plot_loss: true
save_steps: 500
save_strategy: steps
overwrite_output_dir: false
save_only_model: false
report_to: none

# SwanLab 配置
use_swanlab: true
swanlab_project: run-qwen3vl8b-1030  # 可根据需要修改
swanlab_mode: cloud
# swanlab_api_key: pM7Xvs5OS2EeXPO5gKXfJ  # 建议通过环境变量设置，不要硬编码在配置文件中

# --deepspeed /app/examples/deepspeed/ds_z2_config.json
deepspeed: /app/examples/deepspeed/ds_z2_config.json
```

```bash
llamafactory-cli train  /mnt/s3fs/train-LlamaFactory/examples/train_full/qwen3_vl_8b_full.yaml
```


qwen3vl 8b deepspeed用时： 4分钟39秒




LLaMAFactory Megatron的加速（2）速度测试


## 1. Dockerfile.megatron 是什么？

`Dockerfile.megatron` 是用于构建支持 Megatron-Core 训练的 Docker 镜像的 Dockerfile。主要特点：

它安装了：
- `megatron-core==0.13.0`：Megatron 核心库
- `transformer-engine[pytorch]==2.2.0`：Transformer 优化引擎
- `deepspeed==0.16.4`：DeepSpeed 训练框架
- `mcore_adapter`（第65行）：Megatron Core Adapter

## 2. Megatron 训练会更快吗？

通常会更快。Megatron 提供多种优化：

- 模型并行：张量模型并行、流水线模型并行、序列并行
- 融合优化：`bias_activation_fusion`、`apply_rope_fusion`
- 分布式优化器：`use_distributed_optimizer`
- 通信重叠：`overlap_param_gather`、`overlap_grad_reduce`
- 其他：MoE 优化（如 `moe_grouped_gemm`）

示例配置：

```23:35:examples/megatron/qwen3_moe_full.yaml
# mcore speed up
tensor_model_parallel_size: 1
sequence_parallel: false
pipeline_model_parallel_size: 4
bias_activation_fusion: true
apply_rope_fusion: true
use_distributed_optimizer: true
overlap_param_gather: true
overlap_grad_reduce: true
moe_grouped_gemm: true
moe_token_dispatcher_type: alltoall
expert_model_parallel_size: 2
recompute_granularity: full
```

## 3. 如何启用 Megatron 训练？

### 方法一：设置环境变量

设置 `USE_MCA=1` 启用 Megatron Core Adapter：

```bash
export USE_MCA=1
llamafactory-cli train examples/megatron/qwen3_moe_full.yaml
```

代码中的检查逻辑：

```26:36:src/llamafactory/hparams/training_args.py
if is_env_enabled("USE_MCA"):
    if not is_mcore_adapter_available():
        raise ImportError(
            "mcore_adapter is required when USE_MCA=1. Please install `mcore_adapter` and its dependencies."
        )

    from mcore_adapter import Seq2SeqTrainingArguments as McaSeq2SeqTrainingArguments

    BaseTrainingArguments = McaSeq2SeqTrainingArguments
else:
    BaseTrainingArguments = Seq2SeqTrainingArguments
```

- finetuning_type: full  # Megatron 目前只支持 full 微调
- use_mca: true  # 这个参数由 USE_MCA 环境变量控制

### 注意事项

1. 需要安装 `mcore_adapter`：
   ```bash
   pip install "git+https://github.com/alibaba/roll.git#subdirectory=mcore_adapter"
   ```

2. 目前仅支持 `finetuning_type: full`（全量微调），不支持 LoRA。

3. 支持的训练阶段：`pt`（预训练）、`sft`（监督微调）、`dpo`（直接偏好优化）。

4. 训练入口判断逻辑：

```69:83:src/llamafactory/train/tuner.py
    if finetuning_args.stage in ["pt", "sft", "dpo"] and finetuning_args.use_mca:
        if not is_mcore_adapter_available():
            raise ImportError("mcore_adapter is not installed. Please install it with `pip install mcore-adapter`.")
        if finetuning_args.stage == "pt":
            from .mca import run_pt as run_pt_mca

            run_pt_mca(model_args, data_args, training_args, finetuning_args, callbacks)
        elif finetuning_args.stage == "sft":
            from .mca import run_sft as run_sft_mca

            run_sft_mca(model_args, data_args, training_args, finetuning_args, callbacks)
        elif finetuning_args.stage == "dpo":
            from .mca import run_dpo as run_dpo_mca

            run_dpo_mca(model_args, data_args, training_args, finetuning_args, callbacks)
```

总结：设置 `USE_MCA=1` 环境变量，使用支持 Megatron 的 Docker 镜像或安装 `mcore_adapter`，然后在配置文件中设置 Megatron 相关参数即可启用。

## 4. 镜像构建


构建 apex whl 文件的脚本

```bash
#!/bin/bash

# 构建 apex whl 文件的脚本

# 创建输出目录
mkdir -p /workspace/wheels

# 配置 pip 源
export PIP_INDEX=${PIP_INDEX:-https://mirrors.aliyun.com/pypi/simple/}
export PIP_TRUSTED_HOST=${PIP_TRUSTED_HOST:-mirrors.aliyun.com}

# 先安装构建依赖
pip install --no-cache-dir -i ${PIP_INDEX} --trusted-host ${PIP_TRUSTED_HOST} \
    packaging wheel setuptools pyproject-metadata

# 克隆 apex 仓库（指定分支/标签，与 Dockerfile 保持一致）
git clone --depth 1 --branch 25.04 https://github.com/NVIDIA/apex.git /workspace/apex

# 进入 apex 目录
cd /workspace/apex

# 设置环境变量（与 Dockerfile 中保持一致）
export MAX_JOBS=32
export NINJA_FLAGS="-j32"
export NVCC_APPEND_FLAGS="--threads 32"

# 使用 pip wheel 构建 whl 文件（不安装）
# --config-settings 传递构建选项，与 Dockerfile 保持一致
MAX_JOBS=32 NINJA_FLAGS="-j32" NVCC_APPEND_FLAGS="--threads 32" \
pip wheel -v --disable-pip-version-check --no-cache-dir --no-build-isolation \
    --config-settings "--build-option=--cpp_ext --cuda_ext --parallel 32" \
    -w /workspace/wheels .

echo "apex whl 文件已构建完成，保存在 /workspace/wheels 目录"
ls -lh /workspace/wheels/*.whl
```

```bash
docker build -f ./docker/docker-cuda/Dockerfile.megatron \
    --build-arg PIP_INDEX=https://pypi.org/simple \
    --build-arg EXTRAS=metrics，swanlab,vllm \
    -t llamafactory:latest .
```


meiguo机器：

```bash
docker run -it --net host \
  --gpus all \
  --ipc=host \
  --shm-size=8g \
  --ulimit memlock=-1 \
  --ulimit stack=67108864 \
  -v /data/xiedong:/data/xiedong \
  nvcr.io/nvidia/pytorch:25.04-py3 bash


docker run -it --net host \
  --gpus all \
  --ipc=host \
  --shm-size=8g \
  --ulimit memlock=-1 \
  --ulimit stack=67108864 \
  -v /data/xiedong:/data/xiedong \
  kevinchina/deeplearning:llamafactory0-9-4-base-1-megatron-1 bash






export DEBIAN_FRONTEND=noninteractive
export PIP_ROOT_USER_ACTION=ignore

pip install --upgrade pip setuptools wheel "hatchling>=1.18.0" editables --trusted-host ${PYPI_TRUSTED_HOST} --index-url ${PYPI_MIRROR}

pip uninstall -y torch torchvision torch-tensorrt \
    flash_attn transformer-engine \
    cudf dask-cuda cugraph cugraph-service-server cuml raft-dask cugraph-dgl cugraph-pyg dask-cudf

pip install torch==2.6.0 torchvision==0.21.0 torchaudio==2.6.0 --index-url https://download.pytorch.org/whl/cu124

pip uninstall -y opencv opencv-python opencv-python-headless && \
    rm -rf /usr/local/lib/python3.10/dist-packages/cv2/ && \
    pip install opencv-python-headless==4.11.0.86 --trusted-host ${PYPI_TRUSTED_HOST} --index-url ${PYPI_MIRROR}

pip install https://github.com/Dao-AILab/flash-attention/releases/download/v2.7.2.post1/flash_attn-2.7.2.post1+cu12torch2.6cxx11abiFALSE-cp310-cp310-linux_x86_64.whl

apt-get update && apt-get install -y zip

apt-get install -y --no-install-recommends \
    locales \
    aria2 \
    fonts-noto-cjk \
    language-pack-zh-hans \
    zip \
    unzip \
    tree \
    vim \
    tzdata \
    apt-utils \
    htop \
    tmux \
    curl \
    wget \
    git \
    file \
    net-tools \
    libibverbs1 \
    libibverbs-dev \
    build-essential \
    ca-certificates

pip install pybind11 s3fs decord msgspec opencv-python megfile math_verify wandb swanlab
pip install "git+https://github.com/alibaba/roll.git#subdirectory=mcore_adapter"


apt-get install -y openjdk-21-jdk




ENV JAVA_HOME /usr/lib/jvm/java-21-openjdk-amd64


conda update -y openssl || true && \
    apt-get update && \
    DEBIAN_FRONTEND=noninteractive apt-get install -y openssh-server || \
    (DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends openssh-server openssh-client && \
     mkdir -p /etc/ssh && \
     ssh-keygen -A || true)





# wang 机器
docker run -it --net host \
  --ipc=host \
  --shm-size=8g \
  --ulimit memlock=-1 \
  --ulimit stack=67108864 \
  --gpus all \
  -v /data/xiedong:/data/xiedong \
  kevinchina/deeplearning:llamafactory-megatron-base-2 bash


pip install "numpy==1.26.4" "optree>=0.13.0" "spacy==3.7.5" "weasel==0.4.1" \
    transformer-engine[pytorch]==2.2.0 megatron-core==0.13.0 deepspeed==0.16.4 \
    --no-build-isolation

export apex_url=git+https://github.com/NVIDIA/apex.git@25.04
pip uninstall -y apex && \
    MAX_JOBS=2 NINJA_FLAGS="-j2" NVCC_APPEND_FLAGS="--threads 2" \
    pip install -v --disable-pip-version-check --no-cache-dir --no-build-isolation \
    --config-settings "--build-option=--cpp_ext --cuda_ext --parallel 2" ${apex_url}

export LD_LIBRARY_PATH=/usr/local/nvidia/lib64:/usr/lib/x86_64-linux-gnu:$LD_LIBRARY_PATH





# 推送镜像
docker commit fc3b244ee669 kevinchina/deeplearning:llamafactory-megatron-base-4
docker push kevinchina/deeplearning:llamafactory-megatron-base-4
```



```bash
git clone https://github.com/hiyouga/LlamaFactory.git -b v0.9.4 --depth 1 /app
cd /app && pip install --no-cache-dir -e . --no-build-isolation
```


```bash
FORCE_TORCHRUN=1 llamafactory-cli train /path/to/qwen3_vl_2b_full.yaml

USE_MCA=1 llamafactory-cli train /mnt/s3fs/train-LlamaFactory/examples/megatron/qwen3_vl_2b_full.yaml


USE_MCA=1 llamafactory-cli train /data/xiedong/LlamaFactory/examples/megatron/qwen3_full.yaml
```


## 5. 训练

上面的镜像构建累死人。训练报错也是绷不住哭出声音：

```bash
USE_MCA=1 llamafactory-cli train /data/xiedong/LlamaFactory/examples/megatron/qwen3_full.yaml
```


| 参数 | 含义 | 当前值 | 说明 |
|------|------|--------|------|
| `tensor_model_parallel_size` | 张量并行大小 | 1 | 在权重矩阵维度上切分，1=不并行 |
| `pipeline_model_parallel_size` | 流水线并行大小 | 1 | 按层切分到多个 GPU，需要至少对应数量的进程 |
| `sequence_parallel` | 序列并行 | false | 在序列长度维度并行注意力计算 |
| `bias_activation_fusion` | 偏置激活融合 | true | 优化计算，减少内存访问 |
| `apply_rope_fusion` | RoPE 融合 | true | 优化位置编码计算 |
| `use_distributed_optimizer` | 分布式优化器 | true | 优化器状态分片 |


不写了，我留下一篇写。











LLaMAFactory Megatron的加速

用一个具体例子详细说明 GSPO 的两个变体的计算过程，特别是 token 级别的重要性比率是如何得到的。


用一个具体的数值例子说明 GSPO 的两种方式的 token 级别重要性比率计算：

## 假设场景

假设有一个 prompt，模型生成了一个响应："机器学习很实用"

### 输入数据（假设的数值）

假设我们有以下的 log_probs 和 old_log_probs（都是 tensor，shape 为 `(batch_size=1, seq_len=5)`）：

```python
# 响应包含5个token：["机器", "学习", "很", "实用", "<pad>"]
# 但实际只有前4个token有效

log_probs = torch.tensor([
 [-2.0, -1.8, -1.5, -1.2, 0.0] # 当前策略的对数概率
])

old_log_probs = torch.tensor([
 [-2.2, -2.0, -1.6, -1.3, 0.0] # 旧策略的对数概率
])

response_mask = torch.tensor([
 [1, 1, 1, 1, 0] # 前4个token有效，最后一个padding
])
```

## 步骤1：计算 Token 级别的 negative_approx_kl

```python
negative_approx_kl = log_probs - old_log_probs
```

**计算结果：**

| Token位置 | log_probs | old_log_probs | negative_approx_kl |
|----------|-----------|---------------|-------------------|
| 0 ("机器") | -2.0 | -2.2 | -2.0 - (-2.2) = **0.2** |
| 1 ("学习") | -1.8 | -2.0 | -1.8 - (-2.0) = **0.2** |
| 2 ("很") | -1.5 | -1.6 | -1.5 - (-1.6) = **0.1** |
| 3 ("实用") | -1.2 | -1.3 | -1.2 - (-1.3) = **0.1** |
| 4 (padding) | 0.0 | 0.0 | 0.0 - 0.0 = **0.0** |

所以：
```python
negative_approx_kl = torch.tensor([
 [0.2, 0.2, 0.1, 0.1, 0.0]
])
```

## 步骤2：计算序列级别的平均 KL（这是 GSPO 的关键步骤）

```python
negative_approx_kl_in_seq = VF.masked_mean(negative_approx_kl, response_mask, dim=-1)
```

`VF.masked_mean` 会：
1. 只对 mask=1 的位置求平均（忽略 padding）
2. 在最后一个维度（`dim=-1`）上求平均

**计算过程：**
\[
\text{negative_approx_kl_in_seq} = \frac{0.2 + 0.2 + 0.1 + 0.1}{4} = 0.15
\]

**结果：**
```python
negative_approx_kl_in_seq = torch.tensor([0.15]) # shape: (1,)
```

## 步骤3：构建 Token 级别的重要性比率（两种方式）

### 方式A：`gspo`（纯序列级别）

```python
log_importance_ratio = negative_approx_kl_in_seq * response_mask
```

**计算过程：**

1. `negative_approx_kl_in_seq` 的值是 `0.15`（标量）
2. `response_mask` 是 `[1, 1, 1, 1, 0]`
3. 执行广播（broadcast）：
 - `0.15 * 1 = 0.15`（对每个有效token）
 - `0.15 * 0 = 0.0`（对padding）

**结果：**

| Token位置 | negative_approx_kl_in_seq | response_mask | log_importance_ratio |
|----------|---------------------------|---------------|---------------------|
| 0 | 0.15 | 1 | **0.15** |
| 1 | 0.15 | 1 | **0.15** |
| 2 | 0.15 | 1 | **0.15** |
| 3 | 0.15 | 1 | **0.15** |
| 4 | 0.15 | 0 | **0.0** |

```python
log_importance_ratio = torch.tensor([
 [0.15, 0.15, 0.15, 0.15, 0.0]
])
```

特点：所有有效 token 的 `log_importance_ratio` 相同（都是 `0.15`）。

### 方式B：`gspo_token`（序列级别 + Token 级别组合）

```python
log_importance_ratio = negative_approx_kl_in_seq.detach().unsqueeze(-1) + log_probs - log_probs.detach()
```

需要分步说明：

#### 步骤3.1：准备序列级别的部分

```python
negative_approx_kl_in_seq.detach().unsqueeze(-1)
```

- `.detach()`：不参与梯度计算
- `.unsqueeze(-1)`：在最后一个维度扩展，`(1,)` → `(1, 1)`

结果：
```python
# shape: (1, 1) → 广播到 (1, 5)
torch.tensor([[0.15, 0.15, 0.15, 0.15, 0.15]]) # 每个token都是0.15
```

#### 步骤3.2：计算 Token 级别的调整项

```python
log_probs - log_probs.detach()
```

**计算过程：**

| Token位置 | log_probs | log_probs.detach() | 差值 |
|----------|-----------|-------------------|------|
| 0 | -2.0 | -2.0 | **0.0** |
| 1 | -1.8 | -1.8 | **0.0** |
| 2 | -1.5 | -1.5 | **0.0** |
| 3 | -1.2 | -1.2 | **0.0** |
| 4 | 0.0 | 0.0 | **0.0** |

注意：如果 `log_probs` 是从前向传播直接得到的（没有额外的梯度操作），那么 `log_probs - log_probs.detach()` 在当前时刻通常为 0。这里的目的是在后续训练迭代中，`log_probs` 会变化，从而提供 token 级别的梯度信息。

#### 步骤3.3：相加得到最终结果

```python
log_importance_ratio = [0.15, 0.15, 0.15, 0.15, 0.15] + [0.0, 0.0, 0.0, 0.0, 0.0]
 = [0.15, 0.15, 0.15, 0.15, 0.15]
```

更真实的场景：假设在训练过程中，`log_probs` 发生了变化：

```python
# 假设经过一次更新后，log_probs变成了：
log_probs_new = torch.tensor([
 [-1.9, -1.7, -1.4, -1.1, 0.0] # 稍微提高了
])

# 但是之前detach的值还是旧的：
log_probs_old_detached = torch.tensor([
 [-2.0, -1.8, -1.5, -1.2, 0.0]
])

# 那么 token级别的调整项：
token_adjustment = log_probs_new - log_probs_old_detached
 = [-1.9 - (-2.0), -1.7 - (-1.8), -1.4 - (-1.5), -1.1 - (-1.2), 0.0 - 0.0]
 = [0.1, 0.1, 0.1, 0.1, 0.0]

# 序列级别的部分（从negative_approx_kl计算得到，假设还是0.15）：
seq_level = 0.15

# 最终：
log_importance_ratio = seq_level + token_adjustment
 = [0.15 + 0.1, 0.15 + 0.1, 0.15 + 0.1, 0.15 + 0.1, 0.15 + 0.0]
 = [0.25, 0.25, 0.25, 0.25, 0.15]
```

但实际上，在代码中的使用场景，让我重新理解一下...

让我再仔细看看代码逻辑。实际上，`log_probs` 是在每次前向传播时计算的，所以 `log_probs - log_probs.detach()` 在当前前向传播中确实是0。这个设计的目的可能是为了在后续的梯度更新中，让 token 级别的变化能够影响梯度。

让我用更实际的例子来说明：

## 完整例子对比

假设我们有一个 batch，包含 2 个响应：

```python
# Batch size = 2
# Response 1: "机器学习" (4个token)
# Response 2: "很有趣" (3个token)

log_probs = torch.tensor([
 [-2.0, -1.8, -1.5, -1.2, 0.0], # Response 1
 [-1.9, -1.6, -1.3, 0.0, 0.0] # Response 2
])

old_log_probs = torch.tensor([
 [-2.2, -2.0, -1.6, -1.3, 0.0], # Response 1 旧策略
 [-2.1, -1.8, -1.5, 0.0, 0.0] # Response 2 旧策略
])

response_mask = torch.tensor([
 [1, 1, 1, 1, 0], # Response 1: 4个有效token
 [1, 1, 1, 0, 0] # Response 2: 3个有效token
])
```

### 步骤1：计算 negative_approx_kl

```python
negative_approx_kl = log_probs - old_log_probs
```

**Response 1:**
- Token 0: -2.0 - (-2.2) = 0.2
- Token 1: -1.8 - (-2.0) = 0.2
- Token 2: -1.5 - (-1.6) = 0.1
- Token 3: -1.2 - (-1.3) = 0.1
- Token 4: 0.0 - 0.0 = 0.0

**Response 2:**
- Token 0: -1.9 - (-2.1) = 0.2
- Token 1: -1.6 - (-1.8) = 0.2
- Token 2: -1.3 - (-1.5) = 0.2
- Token 3: 0.0 - 0.0 = 0.0
- Token 4: 0.0 - 0.0 = 0.0

```python
negative_approx_kl = torch.tensor([
 [0.2, 0.2, 0.1, 0.1, 0.0], # Response 1
 [0.2, 0.2, 0.2, 0.0, 0.0] # Response 2
])
```

### 步骤2：计算序列级别的平均

```python
negative_approx_kl_in_seq = VF.masked_mean(negative_approx_kl, response_mask, dim=-1)
```

**Response 1:**
\[
\frac{0.2 + 0.2 + 0.1 + 0.1}{4} = 0.15
\]

**Response 2:**
\[
\frac{0.2 + 0.2 + 0.2}{3} = 0.2
\]

```python
negative_approx_kl_in_seq = torch.tensor([0.15, 0.2]) # shape: (2,)
```

### 方式A：`gspo` 计算 log_importance_ratio

```python
log_importance_ratio = negative_approx_kl_in_seq * response_mask
```

**计算过程（广播）：**

**Response 1:**
- 0.15 * [1, 1, 1, 1, 0] = [0.15, 0.15, 0.15, 0.15, 0.0]

**Response 2:**
- 0.2 * [1, 1, 1, 0, 0] = [0.2, 0.2, 0.2, 0.0, 0.0]

**最终结果：**

| 响应 | Token 0 | Token 1 | Token 2 | Token 3 | Token 4 |
|------|---------|---------|---------|---------|---------|
| Response 1 | **0.15** | **0.15** | **0.15** | **0.15** | 0.0 |
| Response 2 | **0.2** | **0.2** | **0.2** | 0.0 | 0.0 |

特点：每个响应内部的所有 token 都有相同的 `log_importance_ratio`。

### 方式B：`gspo_token` 计算 log_importance_ratio

```python
log_importance_ratio = negative_approx_kl_in_seq.detach().unsqueeze(-1) + log_probs - log_probs.detach()
```

由于在当前前向传播中 `log_probs - log_probs.detach()` 为 0，所以：

**Response 1:**
- [0.15, 0.15, 0.15, 0.15, 0.15] + [0, 0, 0, 0, 0] = [0.15, 0.15, 0.15, 0.15, 0.15]

**Response 2:**
- [0.2, 0.2, 0.2, 0.2, 0.2] + [0, 0, 0, 0, 0] = [0.2, 0.2, 0.2, 0.2, 0.2]

但在实际训练中，当 `log_probs` 在梯度更新后变化时，`log_probs - log_probs.detach()` 会提供 token 级别的差异，从而让每个 token 的 `log_importance_ratio` 可以不同。

## 步骤4：转换成 ratio

```python
ratio = torch.exp(log_importance_ratio)
```

对于 `gspo` 方式（Response 1）：
- Token 0: e^0.15 ≈ 1.162
- Token 1: e^0.15 ≈ 1.162
- Token 2: e^0.15 ≈ 1.162
- Token 3: e^0.15 ≈ 1.162

## 总结对比

| 方法 | 每个响应的 token 级别 log_importance_ratio | 特点 |
|------|-------------------------------------------|------|
| **`gspo`** | 所有 token 相同（都是序列级别平均值） | 纯序列级别优化，稳定性高 |
| **`gspo_token`** | 序列级别基础值 + token 级别调整项 | 结合序列和 token 级别信息，更灵活 |

关键在于理解：`gspo` 直接将序列级别的平均值扩展到所有 token，而 `gspo_token` 在序列级别基础上增加了 token 级别的调整项（虽然在当前前向传播中可能为0，但在梯度更新后会体现差异）。