FineTurnX/TRAINING_FIXES.md

训练参数修复说明

问题总结

在运行微调脚本时遇到了两个 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

修改前:

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
    )

修改后:

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

修改前:

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,
)

修改后:

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 安全检查

# 修改前
fp16=fp16

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

2. 添加 remove_unused_columns

remove_unused_columns=False  # 避免数据列被意外移除

验证修复

运行测试脚本:

python test_training_args.py

应该看到:

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

重新运行微调

修复完成后，重新运行微调脚本:

python examples/qwen3.5_0.8b_local_finetune.py

Transformers 版本兼容性

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

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

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

相关资源

• Transformers TrainingArguments 文档
• Transformers 更新日志

常见问题

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