企业官网建设流程全解析

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. CLI

hfjobsuv 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 需要的脚本修改

将这些添加到你的TrainingArguments：

args=SentenceTransformerTrainingArguments(...,push_to_hub=True,hub_model_id="your-username/my-model",hub_strategy="every_save",# 推送每个检查点；超时安全save_strategy="steps",save_steps=0.1,# 每个 epoch 10 次保存/推送；随数据集大小扩展)

每一项为何重要：

机密

机密是注入 Jobs 容器的环境变量。它们永远不会出现在日志中，也不是脚本的一部分。

作业配置中的$HF_TOKEN语法在提交时引用本地环境中的值——字面字符串$HF_TOKEN会被替换为你的令牌值。绝不要在脚本本身中硬编码令牌。

Trackio（本技能中的默认 tracker）使用HF_TOKEN进行认证，所以不需要额外的机密。只有在你使用这些 tracker 时，才切换到上面的 W&B / MLflow 行。

超时

默认是30 分钟，对几乎任何真实训练来说都太短了。显式设置：

"timeout":"2h"# 2 小时"timeout":"90m"# 90 分钟"timeout":"1.5h"# 90 分钟"timeout":7200# 秒，作为整数

规则：估计训练时间 × 1.3。额外的缓冲覆盖模型加载、数据集缓存、检查点保存和 Hub 推送。

超时时，容器会立即被杀掉。只有 Hub 上的数据（hub_strategy="every_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]# 运行中（或所有）作业hfjobsinspect<job-id># 完整配置 + 状态hfjobslogs<job-id>[--follow|--tail N]# 尾随或流式查看日志hfjobscancel<job-id>hfjobshardware# 列出类型 + 小时费率

在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_hub=True+hub_model_id=...+secrets={"HF_TOKEN": "$HF_TOKEN"}。

tracker 无法连接

• Trackio：HF_TOKEN缺失或缺少写入权限。添加"secrets": {"HF_TOKEN": "$HF_TOKEN"}并确保令牌有写入权限。
• W&B：WANDB_API_KEY缺失。添加"secrets": {"HF_TOKEN": "$HF_TOKEN", "WANDB_API_KEY": "$WANDB_API_KEY"}。

第一步就 OOM

类型太小。提升一档（参见hardware_guide.md）。

训练开始但评估永远挂起

eval_strategy="steps"但没有eval_dataset。始终提供评估数据集，或设置eval_strategy="no"。

数据集下载超时

大数据集或冷缓存缓慢。增加timeout或预缓存到持久卷。

CachedMultipleNegativesRankingLoss+gradient_checkpointing=True崩溃

缓存损失与梯度检查点不兼容。禁用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 中的内联模式中。