huggingface-llm-trainer

在 Hugging Face Jobs 上进行 TRL 训练

概述

使用 TRL（Transformer Reinforcement Learning）在完全托管的 Hugging Face 基础设施上训练语言模型。无需配置本地 GPU，模型将在云端 GPU 上训练，结果会自动保存到 Hugging Face Hub。

TRL 提供多种训练方法：

• SFT（监督式微调）- 标准指令微调
• DPO（直接偏好优化）- 基于偏好数据进行对齐
• GRPO（组相对策略优化）- 在线 RL 训练
• 奖励建模 - 为 RLHF 训练奖励模型

TRL 方法详细文档：

hf_doc_search("your query", product="trl")
hf_doc_fetch("https://huggingface.co/docs/trl/sft_trainer")  # SFT
hf_doc_fetch("https://huggingface.co/docs/trl/dpo_trainer")  # DPO
# etc.

另请参阅： references/training_methods.md，了解各方法概述和选择指南

何时使用此技能

在用户希望进行以下操作时使用此技能：

• 在云端 GPU 上微调语言模型，无需本地基础设施
• 使用 TRL 方法（SFT、DPO、GRPO 等）进行训练
• 在 Hugging Face Jobs 基础设施上运行训练任务
• 将训练好的模型转换为 GGUF，以便在本地部署（Ollama、LM Studio、llama.cpp）
• 确保训练好的模型永久保存到 Hub
• 使用采用优化默认设置的现代工作流

何时使用 Unsloth

在以下情况下，使用 Unsloth（references/unsloth.md）代替标准 TRL：

• GPU 内存有限 - Unsloth 使用的 VRAM 约少 60%
• 速度至关重要 - Unsloth 速度约快 2 倍
• 训练大型模型（>13B） - 内存效率至关重要
• 训练视觉语言模型（VLM） - Unsloth 支持 FastVisionModel

请参阅 references/unsloth.md 获取完整的 Unsloth 文档，并参阅 scripts/unsloth_sft_example.py 获取可用于生产环境的训练脚本。

关键指令

协助执行训练任务时：

1. 始终使用 hf_jobs() MCP 工具 - 使用 hf_jobs("uv", {...}) 提交任务，而不是使用 bash trl-jobs 命令。script 参数可直接接收 Python 代码。除非用户明确要求，否则不要保存到本地文件。将脚本内容作为字符串传递给 hf_jobs()。如果用户要求“训练模型”“微调”或类似操作，必须创建训练脚本并立即使用 hf_jobs() 提交任务。

2. 始终包含 Trackio - 每个训练脚本都应包含 Trackio，以便实时监控。请使用 scripts/ 中的示例脚本作为模板。

3. 提交后提供任务详情 - 提交后，提供任务 ID、监控 URL、预计耗时，并说明用户之后可以请求查询状态。

4. 使用示例脚本作为模板 - 参考 scripts/train_sft_example.py、scripts/train_dpo_example.py 等作为起点。

本地脚本执行

仓库脚本使用 PEP 723 内联依赖。使用 uv run 运行：

uv run scripts/estimate_cost.py --help
uv run scripts/dataset_inspector.py --help

前置条件清单

开始任何训练任务前，请确认：

✅ 账户与身份验证

• 拥有 Hugging Face 账户，并订阅 Pro、Team 或 Enterprise 方案（Jobs 需要付费方案）
• 已完成身份验证登录：使用 hf_whoami() 检查
• 用于推送到 Hub 的 HF_TOKEN ⚠️ 至关重要 - 训练环境是临时的，必须推送到 Hub，否则所有训练结果都会丢失
• Token 必须具有写入权限
• 必须在任务配置中传入 secrets={"HF_TOKEN": "$HF_TOKEN"}，以便提供 Token（$HF_TOKEN 语法 引用的是你的实际 Token 值）

✅ 数据集要求

• 数据集必须已存在于 Hub，或可通过 datasets.load_dataset() 加载
• 格式必须与训练方法匹配（SFT："messages"/文本/提示词-补全；DPO：chosen/rejected；GRPO：仅提示词）
• 在进行 GPU 训练前，始终验证未知数据集，以防止格式错误（见下文“数据集验证”部分）
• 数据集大小应适合硬件（演示：在 t4-small 上使用 50-100 个样本；生产：在 a10g-large/a100-large 上使用 1K-10K+ 个样本）

⚠️ 关键设置

• 超时时间必须超过预计训练时间——默认的 30 分钟对大多数训练来说太短。建议至少设置为 1–2 小时。超时后，任务会失败，所有进度都会丢失。
• 必须启用 Hub 推送——配置：push_to_hub=True、hub_model_id="username/model-name"；任务：secrets={"HF_TOKEN": "$HF_TOKEN"}

异步任务指南

⚠️ 重要：训练任务以异步方式运行，可能需要数小时

需要采取的操作

当用户请求训练时：

1. 创建训练脚本，其中需包含 Trackio（以 scripts/train_sft_example.py 为模板）
2. 立即提交，使用 hf_jobs() MCP 工具并在其中内联提供脚本内容——除非用户要求，否则不要保存到文件
3. 报告提交结果，包括任务 ID、监控 URL 和预计耗时
4. 等待用户请求检查状态——不要自动轮询

基本规则

• 任务在后台运行——提交后会立即返回；训练会独立继续
• 初始日志会延迟出现——日志可能需要 30–60 秒才会显示
• 由用户检查状态——等待用户请求状态更新
• 避免轮询——仅在用户请求时检查日志；改为提供监控链接

提交后

向用户提供：

• ✅ 任务 ID 和监控 URL
• ✅ 预计完成时间
• ✅ Trackio 仪表板 URL
• ✅ 说明用户之后可以请求检查状态

回复示例：

✅ Job submitted successfully!

Job ID: abc123xyz
Monitor: https://huggingface.co/jobs/username/abc123xyz

Expected time: ~2 hours
Estimated cost: ~$10

The job is running in the background. Ask me to check status/logs when ready!

快速入门：三种方法

**💡 演示提示：**在较小的 GPU（t4-small）上快速演示时，省略 eval_dataset 和 eval_strategy，可节省约 40% 的内存。仍然可以看到训练损失和学习进度。

序列长度配置

**TRL 配置类使用 max_length（而非 max_seq_length）**来控制分词后的序列长度：

# ✅ CORRECT - If you need to set sequence length
SFTConfig(max_length=512)   # Truncate sequences to 512 tokens
DPOConfig(max_length=2048)  # Longer context (2048 tokens)

# ❌ WRONG - This parameter doesn't exist
SFTConfig(max_seq_length=512)  # TypeError!

默认行为：max_length=1024（从右侧截断）。这适用于大多数训练。

以下情况可覆盖此设置：

• **需要更长的上下文：**设置更大的值（例如 max_length=2048）
• **内存受限：**设置更小的值（例如 max_length=512）
• **视觉模型：**设置 max_length=None（防止图像 token 被截断）

通常无需设置此参数——以下示例使用了合理的默认值。

方法 1：UV 脚本（推荐——默认选择）

UV 脚本使用 PEP 723 内联依赖，实现简洁且自包含的训练。这是 Claude Code 的主要方法。

hf_jobs("uv", {
    "script": """
# /// script
# dependencies = ["trl>=0.12.0", "peft>=0.7.0", "trackio"]
# ///

from datasets import load_dataset
from peft import LoraConfig
from trl import SFTTrainer, SFTConfig
import trackio

dataset = load_dataset("trl-lib/Capybara", split="train")

# Create train/eval split for monitoring
dataset_split = dataset.train_test_split(test_size=0.1, seed=42)

trainer = SFTTrainer(
    model="Qwen/Qwen2.5-0.5B",
    train_dataset=dataset_split["train"],
    eval_dataset=dataset_split["test"],
    peft_config=LoraConfig(r=16, lora_alpha=32),
    args=SFTConfig(
        output_dir="my-model",
        push_to_hub=True,
        hub_model_id="username/my-model",
        num_train_epochs=3,
        eval_strategy="steps",
        eval_steps=50,
        report_to="trackio",
        project="meaningful_prject_name", # project name for the training name (trackio)
        run_name="meaningful_run_name",   # descriptive name for the specific training run (trackio)
    )
)

trainer.train()
trainer.push_to_hub()
""",
    "flavor": "a10g-large",
    "timeout": "2h",
    "secrets": {"HF_TOKEN": "$HF_TOKEN"}
})

**优势：**可直接使用 MCP 工具，代码简洁，依赖以内联方式声明（PEP 723），无需保存文件，完全可控
**适用场景：**Claude Code 中所有训练任务的默认选择、自定义训练逻辑，以及任何需要使用 hf_jobs() 的场景

使用脚本

⚠️ 重要：script 参数接受内联代码（如上所示）或 URL。本地文件路径不可用。

本地路径不可用的原因： 任务在隔离的 Docker 容器中运行，无法访问本地文件系统。脚本必须是：

• 内联代码（自定义训练的推荐方式）
• 可公开访问的 URL
• 私有仓库 URL（需提供 HF_TOKEN）

常见错误：

# ❌ These will all fail
hf_jobs("uv", {"script": "train.py"})
hf_jobs("uv", {"script": "./scripts/train.py"})
hf_jobs("uv", {"script": "/path/to/train.py"})

正确方法：

# ✅ Inline code (recommended)
hf_jobs("uv", {"script": "# /// script\n# dependencies = [...]\n# ///\n\n<your code>"})

# ✅ From Hugging Face Hub
hf_jobs("uv", {"script": "https://huggingface.co/user/repo/resolve/main/train.py"})

# ✅ From GitHub
hf_jobs("uv", {"script": "https://raw.githubusercontent.com/user/repo/main/train.py"})

# ✅ From Gist
hf_jobs("uv", {"script": "https://gist.githubusercontent.com/user/id/raw/train.py"})

**使用本地脚本：**先上传到 HF Hub：

hf repos create my-training-scripts --type model
hf upload my-training-scripts ./train.py train.py
# Use: https://huggingface.co/USERNAME/my-training-scripts/resolve/main/train.py

方法 2：TRL 维护的脚本（官方示例）

TRL 为所有方法提供经过实战验证的脚本。可通过 URL 运行：

hf_jobs("uv", {
    "script": "https://github.com/huggingface/trl/blob/main/trl/scripts/sft.py",
    "script_args": [
        "--model_name_or_path", "Qwen/Qwen2.5-0.5B",
        "--dataset_name", "trl-lib/Capybara",
        "--output_dir", "my-model",
        "--push_to_hub",
        "--hub_model_id", "username/my-model"
    ],
    "flavor": "a10g-large",
    "timeout": "2h",
    "secrets": {"HF_TOKEN": "$HF_TOKEN"}
})

**优势：**无需编写代码，由 TRL 团队维护，经过生产环境验证
**适用场景：**标准 TRL 训练、快速实验，以及不需要自定义代码的情况
**可用资源：**脚本可从 https://github.com/huggingface/trl/tree/main/examples/scripts 获取

在 Hub 上查找更多 UV 脚本

uv-scripts 组织在 Hugging Face Hub 上以数据集的形式提供可直接使用的 UV 脚本：

# Discover available UV script collections
dataset_search({"author": "uv-scripts", "sort": "downloads", "limit": 20})

# Explore a specific collection
hub_repo_details(["uv-scripts/classification"], repo_type="dataset", include_readme=True)

**热门集合：**OCR、分类、合成数据、vllm、数据集创建

方法 3：HF Jobs CLI（直接使用终端命令）

当 hf_jobs() MCP 工具不可用时，直接使用 hf jobs CLI。

⚠️ 重要：CLI 语法规则

# ✅ CORRECT syntax - flags BEFORE script URL
hf jobs uv run --flavor a10g-large --timeout 2h --secrets HF_TOKEN "https://example.com/train.py"

# ❌ WRONG - "run uv" instead of "uv run"
hf jobs run uv "https://example.com/train.py" --flavor a10g-large

# ❌ WRONG - flags AFTER script URL (will be ignored!)
hf jobs uv run "https://example.com/train.py" --flavor a10g-large

# ❌ WRONG - "--secret" instead of "--secrets" (plural)
hf jobs uv run --secret HF_TOKEN "https://example.com/train.py"

关键语法规则：

1. 命令顺序为 hf jobs uv run（不是 hf jobs run uv）
2. 所有标志（--flavor、--timeout、--secrets）都必须放在脚本 URL 之前
3. 使用 --secrets（复数），而不是 --secret
4. 脚本 URL 必须是最后一个位置参数

完整 CLI 示例：

hf jobs uv run \
  --flavor a10g-large \
  --timeout 2h \
  --secrets HF_TOKEN \
  "https://huggingface.co/user/repo/resolve/main/train.py"

通过 CLI 检查作业状态：

hf jobs ps                        # List all jobs
hf jobs logs <job-id>             # View logs
hf jobs inspect <job-id>          # Job details
hf jobs cancel <job-id>           # Cancel a job

方法 4：TRL Jobs 软件包（简化训练）

trl-jobs 软件包提供经过优化的默认设置和一行命令训练。

uvx trl-jobs sft \
  --model_name Qwen/Qwen2.5-0.5B \
  --dataset_name trl-lib/Capybara

优势： 预配置设置、自动集成 Trackio、自动推送到 Hub、一行命令 适用场景： 用户直接在终端中操作（不在 Claude Code 上下文中），快速进行本地实验 代码仓库： https://github.com/huggingface/trl-jobs

⚠️ 在 Claude Code 上下文中，如果 hf_jobs() MCP 工具可用，请优先使用该工具（方法 1）。

硬件选择

模型大小	推荐硬件	成本（约/小时）	用例
<1B 参数	t4-small	~$0.75	仅用于演示、快速测试（不包含评估步骤）
1-3B 参数	t4-medium、l4x1	~$1.50-2.50	开发
3-7B 参数	a10g-small、a10g-large	~$3.50-5.00	生产训练
7-13B 参数	a10g-large、a100-large	~$5-10	大型模型（使用 LoRA）
13B+ 参数	a100-large、a10g-largex2	~$10-20	超大型模型（使用 LoRA）

GPU 类型： cpu-basic/upgrade/performance/xl、t4-small/medium、l4x1/x4、a10g-small/large/largex2/largex4、a100-large、h100/h100x8

指南：

• 对于 >7B 的模型，使用 LoRA/PEFT 以减少内存占用
• TRL/Accelerate 会自动处理多 GPU
• 测试时从较小的硬件配置开始

参见： references/hardware_guide.md，了解详细规格

重要：将结果保存到 Hub

⚠️ 临时环境——必须推送到 Hub

Jobs 环境是临时的。作业结束时，所有文件都会被删除。如果模型没有推送到 Hub，所有训练结果都会丢失。

必需配置

在训练脚本/配置中：

SFTConfig(
    push_to_hub=True,
    hub_model_id="username/model-name",  # MUST specify
    hub_strategy="every_save",  # Optional: push checkpoints
)

在提交作业时：

{
    "secrets": {"HF_TOKEN": "$HF_TOKEN"}  # Enables authentication
}

验证清单

提交前：

• 配置中已设置 push_to_hub=True
• hub_model_id 包含用户名/仓库名
• secrets 参数包含 HF_TOKEN
• 用户拥有目标仓库的写入权限

参见： references/hub_saving.md，了解详细的故障排除方法

超时管理

⚠️ 默认值：30 分钟——训练时间远远不够

设置超时

{
    "timeout": "2h"   # 2 hours (formats: "90m", "2h", "1.5h", or seconds as integer)
}

超时指南

场景	建议时长	备注
快速演示（50-100 个示例）	10-30 分钟	验证设置
开发训练	1-2 小时	小型数据集
生产训练（3-7B 模型）	4-6 小时	完整数据集
使用 LoRA 训练大型模型	3-6 小时	取决于数据集

务必额外预留 20-30% 的缓冲时间，用于加载模型/数据集、保存检查点、推送到 Hub 以及应对网络延迟。

超时后： 作业会立即终止，所有未保存的进度都会丢失，必须从头重新开始

选择基础模型（模型选择）

根据任务类型或基准测试结果确定要训练的模型。

使用 scripts/hf_benchmarks.py 查找特定任务中表现最佳的模型。这有助于用户选择用于训练的基础模型，同时兼顾模型大小和硬件限制。

# Get help on the benchmarks command:
uv run scripts/hf_benchmarks.py --help

示例——选择 OCR 基础模型

# Search for benchmarks containing whose name contains the text `ocr`
uv run scripts/hf_benchmarks.py search --query ocr

# Get the ranked leaderboard for the allenai/olmOCR-bench benchmark 
uv run scripts/hf_benchmarks.py leaderboard allenai/olmOCR-bench

成本估算

规划具有已知参数的作业时，主动提出估算成本。 使用 scripts/estimate_cost.py：

uv run scripts/estimate_cost.py \
  --model meta-llama/Llama-2-7b-hf \
  --dataset trl-lib/Capybara \
  --hardware a10g-large \
  --dataset-size 16000 \
  --epochs 3

输出包括预计时间、成本、建议的超时时长（含缓冲时间）以及优化建议。

适用场景： 用户正在规划作业、询问成本/耗时、选择硬件，或作业运行时间超过 1 小时或成本超过 $5

示例训练脚本

包含所有最佳实践的生产就绪模板：

加载这些脚本，确保操作正确：

• scripts/train_sft_example.py - 完整的 SFT 训练，包含 Trackio、LoRA 和检查点
• scripts/train_dpo_example.py - 用于偏好学习的 DPO 训练
• scripts/train_grpo_example.py - 用于在线 RL 的 GRPO 训练

这些脚本展示了正确的 Hub 保存、Trackio 集成、检查点管理和优化参数。将脚本内容内联传递给 hf_jobs()，或将其用作自定义脚本的模板。

监控与跟踪

Trackio 提供实时指标可视化。完整的设置指南请参阅 references/trackio_guide.md。

要点：

• 将 trackio 添加到依赖项
• 使用 report_to="trackio" and run_name="meaningful_name" 配置训练器

Trackio 配置默认值

除非用户另有指定，否则使用合理的默认值。 使用 Trackio 生成训练脚本时：

默认配置：

• Space ID：{username}/trackio（默认使用 "trackio" 作为 Space 名称）
• 运行命名：除非另有指定，否则使用用户能够识别的名称（例如，描述任务、模型或用途）
• 配置：保持精简，仅包含超参数以及模型/数据集信息
• Project Name：使用 Project Name 将运行与特定 Project 关联起来

用户覆盖项： 如果用户要求特定的 Trackio 配置（自定义 Space、运行命名、分组或其他配置），则采用用户的偏好，而非默认值。

这有助于使用相同配置管理多个作业，或让训练脚本保持可移植性。

完整文档（包括实验运行分组）请参阅 references/trackio_guide.md。

检查作业状态

# List all jobs
hf_jobs("ps")

# Inspect specific job
hf_jobs("inspect", {"job_id": "your-job-id"})

# View logs
hf_jobs("logs", {"job_id": "your-job-id"})

请记住： 等待用户要求检查状态。避免反复轮询。

数据集验证

在启动 GPU 训练前验证数据集格式，避免训练失败的首要原因：格式不匹配。

验证原因

• 50% 以上的训练失败由数据集格式问题导致
• DPO 尤其严格：需要精确的列名（prompt、chosen、rejected）
• GPU 作业失败会浪费 $1-10 和 30-60 分钟
• 在 CPU 上验证成本约为 $0.01，耗时少于 1 分钟

验证时机

以下情况务必验证：

• 未知或自定义数据集
• DPO 训练（至关重要——90% 的数据集需要映射）
• 任何未明确兼容 TRL 的数据集

以下已知的 TRL 数据集可跳过验证：

• trl-lib/ultrachat_200k、trl-lib/Capybara、HuggingFaceH4/ultrachat_200k 等

用法

hf_jobs("uv", {
    "script": "https://huggingface.co/datasets/mcp-tools/skills/raw/main/dataset_inspector.py",
    "script_args": ["--dataset", "username/dataset-name", "--split", "train"]
})

该脚本运行速度很快，通常会同步完成。

读取结果

输出会显示每种训练方法的兼容性：

• ✓ READY - 数据集兼容，可直接使用
• ✗ NEEDS MAPPING - 数据集兼容，但需要预处理（提供映射代码）
• ✗ INCOMPATIBLE - 无法用于此方法

需要映射时，输出会包含一个 “MAPPING CODE” 部分，其中提供可直接复制粘贴的 Python 代码。

示例工作流

# 1. Inspect dataset (costs ~$0.01, <1 min on CPU)
hf_jobs("uv", {
    "script": "https://huggingface.co/datasets/mcp-tools/skills/raw/main/dataset_inspector.py",
    "script_args": ["--dataset", "argilla/distilabel-math-preference-dpo", "--split", "train"]
})

# 2. Check output markers:
#    ✓ READY → proceed with training
#    ✗ NEEDS MAPPING → apply mapping code below
#    ✗ INCOMPATIBLE → choose different method/dataset

# 3. If mapping needed, apply before training:
def format_for_dpo(example):
    return {
        'prompt': example['instruction'],
        'chosen': example['chosen_response'],
        'rejected': example['rejected_response'],
    }
dataset = dataset.map(format_for_dpo, remove_columns=dataset.column_names)

# 4. Launch training job with confidence

常见情况：DPO 格式不匹配

大多数 DPO 数据集使用非标准列名。示例：

Dataset has: instruction, chosen_response, rejected_response
DPO expects: prompt, chosen, rejected

验证器会检测到此问题，并提供用于修复的精确映射代码。

将模型转换为 GGUF

训练完成后，将模型转换为 GGUF 格式，以便在 llama.cpp、Ollama、LM Studio 和其他本地推理工具中使用。

GGUF 简介：

• 针对使用 llama.cpp 进行 CPU/GPU 推理进行了优化
• 支持量化（4-bit、5-bit、8-bit），可缩小模型体积
• 兼容 Ollama、LM Studio、Jan、GPT4All、llama.cpp
• 7B 模型通常为 2-8GB（未量化时为 14GB）

转换时机：

• 使用 Ollama 或 LM Studio 在本地运行模型
• 通过量化缩小模型体积
• 部署到边缘设备
• 分享模型以供本地优先使用

参阅：references/gguf_conversion.md，了解完整的转换指南，包括可用于生产环境的转换脚本、量化选项、硬件要求、用法示例和故障排除。

快速转换：

hf_jobs("uv", {
    "script": "<see references/gguf_conversion.md for complete script>",
    "flavor": "a10g-large",
    "timeout": "45m",
    "secrets": {"HF_TOKEN": "$HF_TOKEN"},
    "env": {
        "ADAPTER_MODEL": "username/my-finetuned-model",
        "BASE_MODEL": "Qwen/Qwen2.5-0.5B",
        "OUTPUT_REPO": "username/my-model-gguf"
    }
})

常见训练模式

参阅 references/training_patterns.md，查看详细示例，包括：

• 快速演示（5-10 分钟）
• 使用检查点进行生产训练
• 多 GPU 训练
• DPO 训练（偏好学习）
• GRPO 训练（在线 RL）

常见故障模式

内存不足（OOM）

修复方法（按顺序尝试）：

1. 减小批次大小：per_device_train_batch_size=1，增大 gradient_accumulation_steps=8。有效批次大小为 per_device_train_batch_size x gradient_accumulation_steps。为获得最佳性能，请将有效批次大小保持在接近 128 的水平。
2. 启用：gradient_checkpointing=True
3. 升级硬件：t4-small → l4x1、a10g-small → a10g-large 等。

数据集格式错误

修复方法：

1. 先使用数据集检查器进行验证：

   uv run https://huggingface.co/datasets/mcp-tools/skills/raw/main/dataset_inspector.py \
     --dataset name --split train
   

2. 检查输出中的兼容性标记（✓ READY、✗ NEEDS MAPPING、✗ INCOMPATIBLE）
3. 如有需要，应用检查器输出中的映射代码

作业超时

修复方法：

1. 检查日志，确认实际运行时间：hf_jobs("logs", {"job_id": "..."})
2. 增加超时时间并留出余量："timeout": "3h"（在预估时间基础上增加 30%）
3. 或缩减训练规模：降低 num_train_epochs、使用较小的数据集、启用 max_steps
4. 保存检查点：save_strategy="steps"、save_steps=500、hub_strategy="every_save"

**注意：**默认的 30 分钟不足以完成实际训练。至少需要 1-2 小时。

推送到 Hub 失败

修复方法：

1. 添加到作业中：secrets={"HF_TOKEN": "$HF_TOKEN"}
2. 添加到配置中：push_to_hub=True、hub_model_id="username/model-name"
3. 验证身份验证：mcp__huggingface__hf_whoami()
4. 检查令牌是否具有写入权限，以及仓库是否存在（或设置 hub_private_repo=True）

缺少依赖项

修复方法： 添加到 PEP 723 标头中：

# /// script
# dependencies = ["trl>=0.12.0", "peft>=0.7.0", "trackio", "missing-package"]
# ///

故障排除

常见问题：

• 作业超时 → 增加超时时间、减少训练轮数/数据集，或使用更小的模型/LoRA
• 模型未保存到 Hub → 检查 push_to_hub=True、hub_model_id、secrets=HF_TOKEN
• 内存不足（OOM）→ 减小批次大小、增大梯度累积、启用 LoRA，或使用更大的 GPU
• 数据集格式错误 → 使用数据集检查器验证（参阅“数据集验证”部分）
• 导入/模块错误 → 添加包含依赖项的 PEP 723 标头，并验证格式
• 身份验证错误 → 检查 mcp__huggingface__hf_whoami()、令牌权限和 secrets 参数

参阅：references/troubleshooting.md，了解完整的故障排除指南

资源

参考资料（本技能中）

• references/training_methods.md - SFT、DPO、GRPO、KTO、PPO 和奖励建模概览
• references/training_patterns.md - 常见训练模式和示例
• references/unsloth.md - 用于快速 VLM 训练的 Unsloth（速度约提升 2 倍，VRAM 使用量减少 60%）
• references/gguf_conversion.md - 完整的 GGUF 转换指南
• references/trackio_guide.md - Trackio 监控设置
• references/hardware_guide.md - 硬件规格和选择
• references/hub_saving.md - Hub 身份验证故障排除
• references/troubleshooting.md - 常见问题和解决方案
• references/local_training_macos.md - 在 macOS 上进行本地训练

脚本（此技能中）

• scripts/train_sft_example.py - 生产级 SFT 模板
• scripts/train_dpo_example.py - 生产级 DPO 模板
• scripts/train_grpo_example.py - 生产级 GRPO 模板
• scripts/unsloth_sft_example.py - Unsloth 文本 LLM 训练模板（速度更快，占用的显存更少）
• scripts/estimate_cost.py - 估算时间和成本（适时提供）
• scripts/convert_to_gguf.py - 完整的 GGUF 转换脚本
• scripts/hf_benchmarks.py - 按任务、别名或自由文本搜索基准测试结果和排行榜。

外部脚本

• 数据集检查器 - 训练前验证数据集格式（通过 uv run 或 hf_jobs 使用）

外部链接

• TRL 文档
• TRL Jobs 训练指南
• TRL Jobs 软件包
• HF Jobs 文档
• TRL 示例脚本
• UV 脚本指南
• UV 脚本组织方式

要点

1. 内联提交脚本 - script 参数可直接接受 Python 代码；除非用户要求，否则无需保存文件
2. Jobs 为异步任务 - 不要等待或轮询；让用户在任务就绪时自行检查
3. 始终设置超时 - 默认的 30 分钟不够；建议至少设置 1–2 小时
4. 始终启用 Hub 推送 - 环境是临时的；不推送的话，所有结果都会丢失
5. 包含 Trackio - 使用示例脚本作为模板，以便实时监控
6. 提供成本估算 - 已知参数时，使用 scripts/estimate_cost.py
7. 使用 UV 脚本（方法 1） - 默认使用 hf_jobs("uv", {...}) 和内联脚本；标准训练使用 TRL 维护的脚本；在 Claude Code 中避免使用 bash trl-jobs 命令
8. 使用 hf_doc_fetch/hf_doc_search 获取最新的 TRL 文档
9. 训练前使用数据集检查器验证数据集格式（参见“数据集验证”部分）
10. 根据模型大小选择合适的硬件；对于 >7B 的模型，使用 LoRA