# 训练参数修复说明

## 问题总结

在运行微调脚本时遇到了两个 `TrainingArguments` 参数问题：

### 问题 1: `max_seq_length` 参数
**错误信息**:
```
TypeError: TrainingArguments.__init__() got an unexpected keyword argument 'max_seq_length'
```

**原因**: `TrainingArguments` 不接受 `max_seq_length` 参数。序列长度应该在数据预处理阶段设置。

**解决方案**: 
- 从 `setup_training()` 方法中移除 `max_seq_length` 参数
- 在创建 `InstructionDataset` 时使用 `max_length` 参数

### 问题 2: `evaluation_strategy` 参数
**错误信息**:
```
TypeError: TrainingArguments.__init__() got an unexpected keyword argument 'evaluation_strategy'
```

**原因**: 在新版本的 Transformers 库中，参数名从 `evaluation_strategy` 改为 `eval_strategy`。

**解决方案**: 
- 将参数名从 `evaluation_strategy` 改为 `eval_strategy`

## 修复内容

### 1. `finetunex/trainer/trainer.py`

修改前:
```python
def setup_training(
    self,
    output_dir: str = "./outputs",
    num_train_epochs: float = 3.0,
    per_device_train_batch_size: int = 1,
    gradient_accumulation_steps: int = 4,
    learning_rate: float = 2e-4,
    max_seq_length: int = 512,          # ❌ 移除
    warmup_ratio: float = 0.03,
    weight_decay: float = 0.01,
    logging_steps: int = 10,
    save_steps: int = 100,
    evaluation_strategy: str = "no",    # ❌ 旧参数名
    save_total_limit: int = 3,
    fp16: bool = True,
    **kwargs
):
    self.training_args = TrainingArguments(
        output_dir=output_dir,
        num_train_epochs=num_train_epochs,
        per_device_train_batch_size=per_device_train_batch_size,
        gradient_accumulation_steps=gradient_accumulation_steps,
        learning_rate=learning_rate,
        max_seq_length=max_seq_length,          # ❌ 移除
        warmup_ratio=warmup_ratio,
        weight_decay=weight_decay,
        logging_steps=logging_steps,
        save_steps=save_steps,
        evaluation_strategy=evaluation_strategy, # ❌ 改为 eval_strategy
        save_total_limit=save_total_limit,
        fp16=fp16,
        optim="paged_adamw_32bit",
        lr_scheduler_type="cosine",
        report_to="none",
        **kwargs
    )
```

修改后:
```python
def setup_training(
    self,
    output_dir: str = "./outputs",
    num_train_epochs: float = 3.0,
    per_device_train_batch_size: int = 1,
    gradient_accumulation_steps: int = 4,
    learning_rate: float = 2e-4,
    warmup_ratio: float = 0.03,
    weight_decay: float = 0.01,
    logging_steps: int = 10,
    save_steps: int = 100,
    eval_strategy: str = "no",          # ✅ 新参数名
    save_total_limit: int = 3,
    fp16: bool = True,
    **kwargs
):
    self.training_args = TrainingArguments(
        output_dir=output_dir,
        num_train_epochs=num_train_epochs,
        per_device_train_batch_size=per_device_train_batch_size,
        gradient_accumulation_steps=gradient_accumulation_steps,
        learning_rate=learning_rate,
        warmup_ratio=warmup_ratio,
        weight_decay=weight_decay,
        logging_steps=logging_steps,
        save_steps=save_steps,
        eval_strategy=eval_strategy,     # ✅ 使用新参数名
        save_total_limit=save_total_limit,
        fp16=fp16 if torch.cuda.is_available() else False,  # ✅ 安全检查
        optim="paged_adamw_32bit",
        lr_scheduler_type="cosine",
        report_to="none",
        remove_unused_columns=False,     # ✅ 添加
        **kwargs
    )
```

### 2. `examples/qwen3.5_0.8b_local_finetune.py`

修改前:
```python
trainer.setup_training(
    output_dir=config.output_dir,
    num_train_epochs=config.num_train_epochs,
    per_device_train_batch_size=config.per_device_train_batch_size,
    gradient_accumulation_steps=config.gradient_accumulation_steps,
    learning_rate=config.learning_rate,
    max_seq_length=config.max_seq_length,  # ❌ 移除
    warmup_ratio=0.03,
    weight_decay=0.01,
    logging_steps=10,
    save_steps=50,
    fp16=True,
)
```

修改后:
```python
trainer.setup_training(
    output_dir=config.output_dir,
    num_train_epochs=config.num_train_epochs,
    per_device_train_batch_size=config.per_device_train_batch_size,
    gradient_accumulation_steps=config.gradient_accumulation_steps,
    learning_rate=config.learning_rate,
    warmup_ratio=0.03,
    weight_decay=0.01,
    logging_steps=10,
    save_steps=50,
    fp16=True,
)
```

## 其他改进

### 1. FP16 安全检查
```python
# 修改前
fp16=fp16

# 修改后
fp16=fp16 if torch.cuda.is_available() else False
```

### 2. 添加 `remove_unused_columns`
```python
remove_unused_columns=False  # 避免数据列被意外移除
```

## 验证修复

运行测试脚本:
```bash
python test_training_args.py
```

应该看到:
```
测试 TrainingArguments 参数...
✓ TrainingArguments 参数验证通过！
  输出目录：./test_output
  训练轮数：3
  FP16: True/False
```

## 重新运行微调

修复完成后，重新运行微调脚本:
```bash
python examples/qwen3.5_0.8b_local_finetune.py
```

## Transformers 版本兼容性

不同版本的 Transformers 可能有不同的参数名：

| 参数 | 旧版本 (<4.30) | 新版本 (>=4.30) |
|------|---------------|----------------|
| 评估策略 | `evaluation_strategy` | `eval_strategy` |
| 最大序列长度 | ❌ 不支持 | ❌ 不支持 |

**建议**: 始终查看你所使用的 Transformers 版本的官方文档。

## 相关资源

- [Transformers TrainingArguments 文档](https://huggingface.co/docs/transformers/main_classes/trainer#transformers.TrainingArguments)
- [Transformers 更新日志](https://github.com/huggingface/transformers/blob/main/CHANGELOG.md)

## 常见问题

### Q: 为什么会有这些参数变化？

A: Transformers 库在不断改进，有时会重命名参数以提高一致性或清晰度。

### Q: 如何避免这类问题？

A: 
1. 使用最新版本的库
2. 查看官方文档和更新日志
3. 在代码中添加版本检查
4. 使用 try-except 捕获兼容性问题

### Q: 如果还有其他参数错误怎么办？

A: 
1. 查看错误信息
2. 搜索 Transformers 文档
3. 检查版本兼容性
4. 必要时使用 **kwargs 传递新参数

---

**修复日期**: 2026-03-30
**修复版本**: 0.1.1