hugging-face-model-trainer

Hugging Face 模型训练

适用场景

适用于使用 TRL 或 Unsloth 规划和运行语言模型 SFT、DPO 或 GRPO 训练，以及准备 GGUF 转换。附带的 Unsloth 示例用于文本训练，并未实现视觉训练或流式支持。请阅读详细指南，并仅查阅任务所需的方法专属参考资料。

执行前

付费任务开始前，用户必须批准确切的训练数据和模型修订版本、目标位置、硬件、时长及计算预算。训练授权不会自动授权公开 Hub 仓库、遥测、跟踪 Spaces 或上传私有数据集。请通过实际服务提供方确认当前账户资格、配额和价格；不要根据旧表格推断。

使用实际可用的受支持 Jobs 接口。提交前检查其当前架构。字符串 $HF_TOKEN 并非通用的机密插值协议。请使用主机文档中说明的机密绑定方式，不要打印凭据、将凭据写入源代码，或更改无关的登录会话。只读操作不需要写入令牌。仅向已获批准的制品目标授予写入权限。

在预留计算资源前，请验证样本值、类型、聊天角色、模型聊天模板以及完整且有界的训练子集。仅凭列名无法证明兼容性。GRPO 还需要明确且经过测试的奖励函数。固定经过审核的依赖版本及不可变的模型和数据集修订版本。单独审核任何必需的远程模型代码；默认使用 trust_remote_code=False。

工作流

1. 确认方法和基线；调整示例前先检查附带的示例。
2. 运行有明确最大步数和样本数的有限试运行。在实际序列长度、精度和优化器配置下验证内存用量。多张 GPU 需要受支持的分布式启动方式；其内存不会自动合并为共享池。
3. 使用试运行测得的时长和用户提供的当前费率运行 scripts/estimate_cost.py --measured-hours 0.1 --hourly-rate 2。 此示例中的数字仅用于计算，不代表服务提供方的价格。
4. 选择不超出已批准预算的截止时间。在临时任务启动前，配置私有且持久的检查点或已批准的存储目标。上传到 Hub 是一种选择；绝不要求公开发布。
5. 检查任务状态和经过清理的日志。检查点恢复并在保留数据上完成评估后，才能判定运行成功。在状态未明确前，不要重新提交结果不确定的任务。

示例

对于 SFT，请根据已批准的模型和文本或聊天数据集调整 scripts/train_sft_example.py。对于偏好学习，请检查 scripts/train_dpo_example.py；对于在线奖励，请检查 scripts/train_grpo_example.py。这些示例需要针对具体环境进行验证，并非经过认证的生产任务。

进行本地转换前，请检查 scripts/convert_to_gguf.py。审核并固定 llama.cpp 及其依赖项。在转换和任何单独获批的上传成功前，保留中间制品。遵守基础模型、适配器和数据的许可证；生成的模型卡无法赋予你原本不具备的权利。

限制

Unsloth 的性能和支持的架构取决于版本、内核、硬件及工作负载；百分比并非保证值。费用辅助工具只执行计算，不进行内存估算、运行时间预测或实时报价。本次源代码审查并未实际执行 GPU 训练、模型加载、上传或外部跟踪。参考资料可能展示较旧的 API 版本；执行前请根据已固定的环境确认并调整。不要将禁用 MPS 内存水位线作为通用的内存不足解决办法。