Hugging Face Jobs 执行在 Hugging Face 托管的 GPU 上运行训练无需配置任何本地基础设施。同一个训练脚本可以在本地和 Jobs 上运行——本参考只涵盖 Jobs 特有的问题。前提条件具有Pro、Team 或 Enterprise计划的 Hugging Face 账户。Jobs 是付费的。具有写入权限的HF_TOKEN。本地用hf auth login登录一次来自hfCLI 的现代命令较旧的huggingface-cli login仍然可用但已弃用。可访问hf_jobs()MCP 工具或hfCLI。如果从托管脚本安装 CLI请将其下载到临时文件、检查后本地运行。三种提交方式1. 通过 MCP 内联脚本在 Claude Code 中推荐将完整训练脚本作为script传入。依赖来自 PEP 723 头部。hf_jobs(uv,{script: # /// script # requires-python 3.10 # dependencies [sentence-transformers[train]5.0, trackio] # /// # full training script content ,flavor:a10g-large,timeout:3h,secrets:{HF_TOKEN:$HF_TOKEN},})2. 通过 MCP 从 URL 获取脚本将脚本上传到 Hub作为模型或数据集仓库文件或 Gist然后通过 URL 引用hf_jobs(uv,{script:https://huggingface.co/USERNAME/scripts/resolve/main/train_bi_encoder.py,flavor:a10g-large,timeout:3h,secrets:{HF_TOKEN:$HF_TOKEN},})本地文件路径./train.py、/path/to/train.py不工作——Jobs 在隔离容器中运行无法访问你的文件系统。3. CLIhfjobsuv run\--flavora10g-large\--timeout3h\--secretsHF_TOKEN\https://huggingface.co/USERNAME/scripts/resolve/main/train.py语法陷阱命令顺序是hf jobs uv run不是hf jobs run uv。标志--flavor、--timeout、--secrets在脚本 URL之前。是--secrets复数不是--secret。Jobs 需要的脚本修改将这些添加到你的TrainingArgumentsargsSentenceTransformerTrainingArguments(...,push_to_hubTrue,hub_model_idyour-username/my-model,hub_strategyevery_save,# 推送每个检查点超时安全save_strategysteps,save_steps0.1,# 每个 epoch 10 次保存/推送随数据集大小扩展)每一项为何重要参数原因push_to_hubTrue作业完成后 Jobs 容器会被销毁。没有 Hub 推送所有权重都会丢失。hub_model_id识别目标仓库所必需。hub_strategyevery_save默认值但在 Jobs 上值得明确设置每个检查点在写入时即被推送因此超时会把所有已完成的检查点留在 Hub 上。end只在trainer.train()返回后推送一次所以超时会丢失一切。save_strategystepssave_steps0.1检查点必须实际保存hub_strategyevery_save才能推送它们。小数0.1 每训练 10% 保存一次随数据集大小自动扩展。机密机密是注入 Jobs 容器的环境变量。它们永远不会出现在日志中也不是脚本的一部分。机密何时需要HF_TOKEN总是需要用于 Hub 推送。也覆盖 Trackio 认证。WANDB_API_KEY使用report_towandb时。MLFLOW_TRACKING_URI、MLFLOW_TRACKING_TOKEN将 MLflow 与远程服务器一起使用时。作业配置中的$HF_TOKEN语法在提交时引用本地环境中的值——字面字符串$HF_TOKEN会被替换为你的令牌值。绝不要在脚本本身中硬编码令牌。Trackio本技能中的默认 tracker使用HF_TOKEN进行认证所以不需要额外的机密。只有在你使用这些 tracker 时才切换到上面的 WB / MLflow 行。超时默认是30 分钟对几乎任何真实训练来说都太短了。显式设置timeout:2h# 2 小时timeout:90m# 90 分钟timeout:1.5h# 90 分钟timeout:7200# 秒作为整数规则估计训练时间 × 1.3。额外的缓冲覆盖模型加载、数据集缓存、检查点保存和 Hub 推送。超时时容器会立即被杀掉。只有 Hub 上的数据hub_strategyevery_save在这里救你或持久卷中的数据能存活。数据集缓存Hugging Face 数据集默认缓存在~/.cache/huggingface/datasets——在容器内部而容器在作业结束后会被销毁。每次 Jobs 运行都会重新下载数据集。对于大数据集5 GB这很重要。选项持久/data卷Jobs 功能查看当前文档设置HF_DATASETS_CACHE/data/datasets使缓存跨作业持久化。本地预缓存推送到 Hub如果数据集已在 Hub 上无需操作。如果仅本地dataset.push_to_hub(...)一次这样后续作业从 Hub 加载。监控正在运行的作业hfjobsps[--all]# 运行中或所有作业hfjobsinspectjob-id# 完整配置 状态hfjobslogsjob-id[--follow|--tail N]# 尾随或流式查看日志hfjobscanceljob-idhfjobshardware# 列出类型 小时费率在Bash run_in_background下的hf jobs logs id --follow与监控你训练脚本 verdict 块发出的VERDICT:行的Monitor配合得很好。MCP 等价物签名可能因服务器版本而异——检查实际的工具列表hf_jobs(ps)、hf_jobs(logs, {job_id: ...})、hf_jobs(cancel, {job_id: ...})。对于定期运行hf jobs scheduled uv run cron script ...进行调度hf jobs scheduled ps/suspend/delete进行管理。常见失败看起来成功的运行后Hub 上找不到模型运行成功了但没有启用push_to_hub。容器已经没了权重也没了。修复始终设置push_to_hubTruehub_model_id...secrets{HF_TOKEN: $HF_TOKEN}。tracker 无法连接TrackioHF_TOKEN缺失或缺少写入权限。添加secrets: {HF_TOKEN: $HF_TOKEN}并确保令牌有写入权限。WBWANDB_API_KEY缺失。添加secrets: {HF_TOKEN: $HF_TOKEN, WANDB_API_KEY: $WANDB_API_KEY}。第一步就 OOM类型太小。提升一档参见hardware_guide.md。训练开始但评估永远挂起eval_strategysteps但没有eval_dataset。始终提供评估数据集或设置eval_strategyno。数据集下载超时大数据集或冷缓存缓慢。增加timeout或预缓存到持久卷。CachedMultipleNegativesRankingLossgradient_checkpointingTrue崩溃缓存损失与梯度检查点不兼容。禁用gradient_checkpointing。提交后MCP 返回一个作业 ID。需要更新时用hf_jobs(logs, {job_id: ...})监控——不要在紧凑循环中轮询。端到端提交模板位于scripts/train_sentence_transformer_example.py/scripts/train_cross_encoder_example.py/scripts/train_sparse_encoder_example.py将脚本内容包装在 §1 中的内联模式中。