huggingface-jobs

Hugging Face Jobs でワークロードを実行する

概要

完全マネージドの Hugging Face インフラストラクチャで、あらゆるワークロードを実行できます。ローカルでのセットアップは不要です。ジョブはクラウドの CPU、GPU、または TPU で実行され、結果を Hugging Face Hub に保存できます。

一般的なユースケース：

• データ処理 - 大規模なデータセットを変換、フィルタリング、または分析する
• バッチ推論 - 数千件のサンプルに対して推論を実行する
• 実験とベンチマーク - 再現可能な ML 実験
• モデルのトレーニング - モデルをファインチューニングする（TRL 固有のトレーニングについては model-trainer スキルを参照してください）
• 合成データの生成 - LLM を使用してデータセットを生成する
• 開発とテスト - ローカルで GPU をセットアップせずにコードをテストする
• スケジュール済みジョブ - 定期的なタスクを自動化する

特にモデルのトレーニングを行う場合： TRL ベースのトレーニングワークフローについては、model-trainer スキルを参照してください。

このスキルを使用する場面

ユーザーが次のことを希望する場合に、このスキルを使用してください。

• クラウドインフラストラクチャで Python ワークロードを実行する
• ローカルで GPU／TPU をセットアップせずにジョブを実行する
• 大規模にデータを処理する
• バッチ推論や実験を実行する
• 定期的なタスクをスケジュールする
• あらゆるワークロードで GPU／TPU を使用する
• 結果を Hugging Face Hub に保存する

重要な指示

ジョブを支援する際は、次の点に従ってください。

1. 必ず hf_jobs() MCP ツールを使用してください - hf_jobs("uv", {...}) または hf_jobs("run", {...}) を使用してジョブを送信します。script パラメーターには Python コードを直接指定できます。ユーザーから明示的に依頼されない限り、ローカルファイルには保存しないでください。スクリプトの内容は文字列として hf_jobs() に渡してください。

2. 必ず認証を処理してください - Hub と連携するジョブには、シークレット経由で HF_TOKEN が必要です。詳細は、以下の「トークンの使用」セクションを参照してください。

3. 送信後にジョブの詳細を提示してください - 送信後、ジョブ ID、監視用 URL、推定所要時間を伝え、後からステータスを確認できることをユーザーに知らせてください。

4. 適切なタイムアウトを設定してください - デフォルトの 30 分では、長時間実行されるタスクには不十分な場合があります。

前提条件のチェックリスト

ジョブを開始する前に、次の項目を確認してください。

✅ アカウントと認証

• Hugging Face アカウントに Pro、Team、または Enterprise プランがあること（Jobs には有料プランが必要です）
• ログイン認証済みであること：hf_whoami() で確認します
• Hub アクセス用の HF_TOKEN ⚠️ 重大 - Hub に対する操作（モデル／データセットのプッシュ、非公開リポジトリのダウンロードなど）に必須です
• トークンに適切な権限があること（ダウンロードには読み取り、アップロードには書き込み）

✅ トークンの使用（詳細は「トークンの使用」セクションを参照してください）

トークンが必要な場合：

• モデル／データセットを Hub にプッシュする
• 非公開リポジトリにアクセスする
• スクリプトで Hub API を使用する
• 認証が必要な Hub 操作を行う

トークンの指定方法：

# hf_jobs MCP tool — $HF_TOKEN is auto-replaced with real token:
{"secrets": {"HF_TOKEN": "$HF_TOKEN"}}

# HfApi().run_uv_job() — MUST pass actual token:
from huggingface_hub import get_token
secrets={"HF_TOKEN": get_token()}

⚠️ 重大： $HF_TOKEN プレースホルダーが自動的に置き換えられるのは、hf_jobs MCP ツールを使用する場合のみです。HfApi().run_uv_job() を使用する場合は、get_token() を使って実際のトークンを渡す必要があります。文字列 "$HF_TOKEN" をそのまま渡すと、9 文字の無効なトークンとなり、401 エラーが発生します。

トークンの使用ガイド

トークンについて

HF トークンとは何ですか？

• Hugging Face Hub の認証情報です
• 認証が必要な操作（プッシュ、非公開リポジトリ、API アクセス）に必要です
• hf auth login の実行後、マシンに安全に保存されます

トークンの種類：

• 読み取りトークン - モデル／データセットをダウンロードし、非公開リポジトリを読み取ることができます
• 書き込みトークン - モデル／データセットをプッシュし、リポジトリを作成し、コンテンツを変更できます
• 組織トークン - 組織を代表して操作できます

トークンが必要な場合

常に必要：

• モデル／データセットを Hub にプッシュする
• 非公開リポジトリにアクセスする
• 新しいリポジトリを作成する
• 既存のリポジトリを変更する
• プログラムから Hub API を使用する

不要：

• 公開モデル／データセットをダウンロードする
• Hub と連携しないジョブを実行する
• 公開リポジトリの情報を読み取る

ジョブへのトークンの指定方法

方法 1：自動トークン（推奨）

hf_jobs("uv", {
    "script": "your_script.py",
    "secrets": {"HF_TOKEN": "$HF_TOKEN"}  # ✅ Automatic replacement
})

仕組み：

• $HF_TOKEN は、実際のトークンに置き換えられるプレースホルダーです
• ログイン済みセッション（hf auth login）のトークンを使用します
• 最も安全で便利な方法です
• シークレットとして渡すと、トークンはサーバー側で暗号化されます

メリット：

• コード内でトークンが露出しません
• 現在のログインセッションを使用します
• 再ログインすると自動的に更新されます
• MCP ツールとシームレスに連携します

方法 2：明示的なトークン（非推奨）

hf_jobs("uv", {
    "script": "your_script.py",
    "secrets": {"HF_TOKEN": "hf_abc123..."}  # ⚠️ Hardcoded token
})

使用する場合：

• 自動トークンが機能しない場合のみ
• 特定のトークンを使ったテスト
• 組織のトークン（注意して使用してください）

セキュリティ上の懸念：

• コードやログにトークンが表示されます
• トークンがローテーションされた場合、手動で更新する必要があります
• トークンが露出するリスクがあります

方法 3：環境変数（安全性が低い）

hf_jobs("uv", {
    "script": "your_script.py",
    "env": {"HF_TOKEN": "hf_abc123..."}  # ⚠️ Less secure than secrets
})

シークレットとの違い：

• env 変数はジョブのログに表示されます
• secrets はサーバー側で暗号化されます
• トークンには常に secrets を使用してください

スクリプトでのトークンの使用

Python スクリプトでは、トークンを環境変数として利用できます：

# /// script
# dependencies = ["huggingface-hub"]
# ///

import os
from huggingface_hub import HfApi

# Token is automatically available if passed via secrets
token = os.environ.get("HF_TOKEN")

# Use with Hub API
api = HfApi(token=token)

# Or let huggingface_hub auto-detect
api = HfApi()  # Automatically uses HF_TOKEN env var

ベストプラクティス：

• スクリプトにトークンをハードコードしないでください
• os.environ.get("HF_TOKEN") を使用してアクセスしてください
• 可能な場合は huggingface_hub に自動検出させてください
• Hub の操作前にトークンの存在を確認してください

トークンの検証

ログイン状態を確認する：

from huggingface_hub import whoami
user_info = whoami()  # Returns your username if authenticated

ジョブ内のトークンを検証する：

import os
assert "HF_TOKEN" in os.environ, "HF_TOKEN not found!"
token = os.environ["HF_TOKEN"]
print(f"Token starts with: {token[:7]}...")  # Should start with "hf_"

よくあるトークンの問題

エラー：401 Unauthorized

• 原因： トークンがないか、無効です
• 修正方法： ジョブ設定に secrets={"HF_TOKEN": "$HF_TOKEN"} を追加します
• 確認方法： ローカルで hf_whoami() が動作することを確認します

エラー：403 Forbidden

• 原因： トークンに必要な権限がありません
• 修正方法： プッシュ操作には、トークンに書き込み権限があることを確認します
• 確認方法： https://huggingface.co/settings/tokens でトークンの種類を確認します

エラー：環境内にトークンが見つかりません

• 原因： secrets が渡されていないか、キー名が間違っています
• 修正方法： secrets={"HF_TOKEN": "$HF_TOKEN"} を使用します（env ではありません）
• 確認方法： スクリプトが os.environ.get("HF_TOKEN") を確認します

エラー：リポジトリへのアクセスが拒否されました

• 原因： トークンにプライベートリポジトリへのアクセス権がありません
• 修正方法： アクセス権のあるアカウントのトークンを使用します
• 確認方法： リポジトリの公開設定と自分の権限を確認します

トークンのセキュリティに関するベストプラクティス

1. トークンをコミットしない - $HF_TOKEN プレースホルダーまたは環境変数を使用します
2. env ではなく secrets を使用する - Secrets はサーバー側で暗号化されます
3. トークンを定期的にローテーションする - 定期的に新しいトークンを生成します
4. 必要最小限の権限を使用する - 必要な権限のみを持つトークンを作成します
5. トークンを共有しない - 各ユーザーが自分のトークンを使用します
6. トークンの使用状況を監視する - Hub の設定でトークンのアクティビティを確認します

トークンの完全な例

# Example: Push results to Hub
hf_jobs("uv", {
    "script": """
# /// script
# dependencies = ["huggingface-hub", "datasets"]
# ///

import os
from huggingface_hub import HfApi
from datasets import Dataset

# Verify token is available
assert "HF_TOKEN" in os.environ, "HF_TOKEN required!"

# Use token for Hub operations
api = HfApi(token=os.environ["HF_TOKEN"])

# Create and push dataset
data = {"text": ["Hello", "World"]}
dataset = Dataset.from_dict(data)
dataset.push_to_hub("username/my-dataset", token=os.environ["HF_TOKEN"])

print("✅ Dataset pushed successfully!")
""",
    "flavor": "cpu-basic",
    "timeout": "30m",
    "secrets": {"HF_TOKEN": "$HF_TOKEN"}  # ✅ Token provided securely
})

クイックスタート：2 つのアプローチ

アプローチ 1：UV スクリプト（推奨）

UV スクリプトでは PEP 723 のインライン依存関係を使用し、すっきりとした自己完結型のワークロードを実現します。

MCP ツール：

hf_jobs("uv", {
    "script": """
# /// script
# dependencies = ["transformers", "torch"]
# ///

from transformers import pipeline
import torch

# Your workload here
classifier = pipeline("sentiment-analysis")
result = classifier("I love Hugging Face!")
print(result)
""",
    "flavor": "cpu-basic",
    "timeout": "30m"
})

CLI による同等の方法：

hf jobs uv run my_script.py --flavor cpu-basic --timeout 30m

Python API：

from huggingface_hub import run_uv_job
run_uv_job("my_script.py", flavor="cpu-basic", timeout="30m")

メリット： MCP ツールを直接使用でき、コードがすっきりします。依存関係はインラインで宣言され、ファイルを保存する必要はありません

使用する場合： すべてのワークロードでの標準的な選択肢、カスタムロジック、hf_jobs() が必要なあらゆるシナリオ

UV スクリプト用のカスタム Docker イメージ

デフォルトでは、UV スクリプトは ghcr.io/astral-sh/uv:python3.12-bookworm-slim を使用します。依存関係が複雑な ML ワークロードでは、事前構築済みイメージを使用します：

hf_jobs("uv", {
    "script": "inference.py",
    "image": "vllm/vllm-openai:latest",  # Pre-built image with vLLM
    "flavor": "a10g-large"
})

CLI：

hf jobs uv run --image vllm/vllm-openai:latest --flavor a10g-large inference.py

メリット： 起動が高速で、依存関係が事前にインストールされており、特定のフレームワーク向けに最適化されています

Python のバージョン

デフォルトでは、UV スクリプトは Python 3.12 を使用します。別のバージョンを指定します：

hf_jobs("uv", {
    "script": "my_script.py",
    "python": "3.11",  # Use Python 3.11
    "flavor": "cpu-basic"
})

Python API：

from huggingface_hub import run_uv_job
run_uv_job("my_script.py", python="3.11")

スクリプトの操作

⚠️ 重要： Jobs の実行方法によって、「スクリプトパス」の扱いが 2 通り あります。

• hf_jobs() MCP ツールを使用する場合（このリポジトリで推奨）：script の値は インラインコード（文字列）または URL にする必要があります。ローカルファイルシステムのパス（"./scripts/foo.py" など）はリモートコンテナ内に存在しません。
• hf jobs uv run CLI を使用する場合：ローカルファイルパスを使用できます（CLI がスクリプトをアップロードします）。

hf_jobs() MCP ツールでよくある間違い：

# ❌ Will fail (remote container can't see your local path)
hf_jobs("uv", {"script": "./scripts/foo.py"})

hf_jobs() MCP ツールでの正しいパターン：

# ✅ Inline: read the local script file and pass its *contents*
from pathlib import Path
script = Path("hf-jobs/scripts/foo.py").read_text()
hf_jobs("uv", {"script": script})

# ✅ URL: host the script somewhere reachable
hf_jobs("uv", {"script": "https://huggingface.co/datasets/uv-scripts/.../raw/main/foo.py"})

# ✅ URL from GitHub
hf_jobs("uv", {"script": "https://raw.githubusercontent.com/huggingface/trl/main/trl/scripts/sft.py"})

CLI での同等の方法（ローカルパスをサポート）：

hf jobs uv run ./scripts/foo.py -- --your --args

実行時に依存関係を追加する

PEP 723 ヘッダーに記載されたもの以外の追加の依存関係を指定します。

hf_jobs("uv", {
    "script": "inference.py",
    "dependencies": ["transformers", "torch>=2.0"],  # Extra deps
    "flavor": "a10g-small"
})

Python API：

from huggingface_hub import run_uv_job
run_uv_job("inference.py", dependencies=["transformers", "torch>=2.0"])

アプローチ 2：Docker ベースの Jobs

カスタム Docker イメージとコマンドを使用してジョブを実行します。

MCP ツール：

hf_jobs("run", {
    "image": "python:3.12",
    "command": ["python", "-c", "print('Hello from HF Jobs!')"],
    "flavor": "cpu-basic",
    "timeout": "30m"
})

CLI での同等の方法：

hf jobs run python:3.12 python -c "print('Hello from HF Jobs!')"

Python API：

from huggingface_hub import run_job
run_job(image="python:3.12", command=["python", "-c", "print('Hello!')"], flavor="cpu-basic")

メリット： Docker を完全に制御でき、ビルド済みイメージを使用して、任意のコマンドを実行できます 使用する場面： 特定の Docker イメージが必要な場合、Python 以外のワークロードの場合、複雑な環境を扱う場合

GPU を使用する例：

hf_jobs("run", {
    "image": "pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel",
    "command": ["python", "-c", "import torch; print(torch.cuda.get_device_name())"],
    "flavor": "a10g-small",
    "timeout": "1h"
})

Hugging Face Spaces をイメージとして使用する：

HF Spaces の Docker イメージを使用できます。

hf_jobs("run", {
    "image": "hf.co/spaces/lhoestq/duckdb",  # Space as Docker image
    "command": ["duckdb", "-c", "SELECT 'Hello from DuckDB!'"],
    "flavor": "cpu-basic"
})

CLI：

hf jobs run hf.co/spaces/lhoestq/duckdb duckdb -c "SELECT 'Hello!'"

Hub で UV スクリプトをさらに見つける

uv-scripts organization では、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、データセット作成

ハードウェアの選択

参考： HF Jobs ハードウェアのドキュメント（更新日：2025 年 7 月）

ワークロードの種類	推奨ハードウェア	用途
データ処理、テスト	cpu-basic、cpu-upgrade	軽量なタスク
小規模モデル、デモ	t4-small	1B 未満のモデル、簡易テスト
中規模モデル	t4-medium、l4x1	1～7B のモデル
大規模モデル、本番環境	a10g-small、a10g-large	7～13B のモデル
超大規模モデル	a100-large	13B 以上のモデル
バッチ推論	a10g-large、a100-large	高スループット
マルチ GPU ワークロード	l4x4、a10g-largex2、a10g-largex4	並列処理／大規模モデル
TPU ワークロード	v5e-1x1、v5e-2x2、v5e-2x4	JAX/Flax、TPU に最適化された処理

利用可能なすべてのフレーバー：

• CPU： cpu-basic、cpu-upgrade
• GPU： t4-small、t4-medium、l4x1、l4x4、a10g-small、a10g-large、a10g-largex2、a10g-largex4、a100-large
• TPU： v5e-1x1、v5e-2x2、v5e-2x4

ガイドライン：

• テストでは小規模なハードウェアから始めます
• 実際のニーズに応じてスケールアップします
• 並列ワークロードや大規模モデルにはマルチ GPU を使用します
• JAX/Flax のワークロードには TPU を使用します
• 詳細な仕様については references/hardware_guide.md を参照してください

重要：結果の保存

⚠️ 一時的な環境です――結果を必ず永続化してください

Jobs の環境は一時的です。ジョブが終了すると、すべてのファイルが削除されます。結果を永続化しないと、作業内容がすべて失われます。

永続化の方法

1. Hugging Face Hub にプッシュする（推奨）

# Push models
model.push_to_hub("username/model-name", token=os.environ["HF_TOKEN"])

# Push datasets
dataset.push_to_hub("username/dataset-name", token=os.environ["HF_TOKEN"])

# Push artifacts
api.upload_file(
    path_or_fileobj="results.json",
    path_in_repo="results.json",
    repo_id="username/results",
    token=os.environ["HF_TOKEN"]
)

2. 外部ストレージを使用する

# Upload to S3, GCS, etc.
import boto3
s3 = boto3.client('s3')
s3.upload_file('results.json', 'my-bucket', 'results.json')

3. API 経由で結果を送信する

# POST results to your API
import requests
requests.post("https://your-api.com/results", json=results)

Hub へのプッシュに必要な設定

ジョブの送信時：

# hf_jobs MCP tool:
{"secrets": {"HF_TOKEN": "$HF_TOKEN"}}  # auto-replaced

# HfApi().run_uv_job():
from huggingface_hub import get_token
secrets={"HF_TOKEN": get_token()}  # must pass real token

スクリプト内：

import os
from huggingface_hub import HfApi

# Token automatically available from secrets
api = HfApi(token=os.environ.get("HF_TOKEN"))

# Push your results
api.upload_file(...)

確認項目

送信前に確認してください。

• 結果の永続化方法を選択済み
• Hub を使用する場合、トークンをシークレットに設定済み（MCP："$HF_TOKEN"、Python API：get_token()）
• トークンがない場合もスクリプトが適切に処理する
• 永続化の方法が動作することをテスト済み

参照： Hub への永続化の詳しいガイドは references/hub_saving.md を参照してください

タイムアウトの管理

⚠️ デフォルト：30 分

ジョブはタイムアウト後に自動的に停止します。トレーニングなど、長時間実行するタスクでは、必ずカスタムタイムアウトを設定してください。

タイムアウトの設定

MCP ツール：

{
    "timeout": "2h"   # 2 hours
}

サポートされる形式：

• 整数／小数：秒（例：300 = 5 分）
• 接尾辞付きの文字列："5m"（分）、"2h"（時間）、"1d"（日）
• 例："90m"、"2h"、"1.5h"、300、"1d"

Python API：

from huggingface_hub import run_job, run_uv_job

run_job(image="python:3.12", command=[...], timeout="2h")
run_uv_job("script.py", timeout=7200)  # 2 hours in seconds

タイムアウトのガイドライン

シナリオ	推奨時間	備考
簡単なテスト	10-30 min	セットアップを確認
データ処理	1-2 hours	データサイズによります
バッチ推論	2-4 hours	大規模なバッチ
実験	4-8 hours	複数回の実行
長時間実行	8-24 hours	本番環境のワークロード

セットアップ、ネットワーク遅延、クリーンアップのため、常に20-30%の余裕を加えてください。

**タイムアウト時：**ジョブは直ちに強制終了され、保存されていない進捗はすべて失われます

コストの見積もり

一般的なガイドライン：

Total Cost = (Hours of runtime) × (Cost per hour)

計算例：

簡単なテスト：

• ハードウェア：cpu-basic ($0.10/hour)
• 時間：15分（0.25時間）
• コスト：$0.03

データ処理：

• ハードウェア：l4x1 ($2.50/hour)
• 時間：2時間
• コスト：$5.00

バッチ推論：

• ハードウェア：a10g-large ($5/hour)
• 時間：4時間
• コスト：$20.00

コスト最適化のヒント：

1. 小さく始める - cpu-basic または t4-small でテストします
2. 実行時間を監視する - 適切なタイムアウトを設定します
3. チェックポイントを使用する - ジョブが失敗した場合に再開します
4. コードを最適化する - 不要な計算を減らします
5. 適切なハードウェアを選ぶ - 過剰なプロビジョニングを避けます

監視と追跡

ジョブのステータスを確認する

MCP ツール：

# 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"})

# Cancel a job
hf_jobs("cancel", {"job_id": "your-job-id"})

Python API：

from huggingface_hub import list_jobs, inspect_job, fetch_job_logs, cancel_job

# List your jobs
jobs = list_jobs()

# List running jobs only
running = [j for j in list_jobs() if j.status.stage == "RUNNING"]

# Inspect specific job
job_info = inspect_job(job_id="your-job-id")

# View logs
for log in fetch_job_logs(job_id="your-job-id"):
    print(log)

# Cancel a job
cancel_job(job_id="your-job-id")

CLI：

hf jobs ps                    # List jobs
hf jobs logs <job-id>         # View logs
hf jobs cancel <job-id>       # Cancel job

**注意：**ユーザーからステータス確認を依頼されるまで待ってください。繰り返しポーリングするのは避けてください。

ジョブの URL

送信後、ジョブには監視用 URL が割り当てられます：

https://huggingface.co/jobs/username/job-id

ブラウザーでログ、ステータス、詳細を確認できます。

複数のジョブを待つ

import time
from huggingface_hub import inspect_job, run_job

# Run multiple jobs
jobs = [run_job(image=img, command=cmd) for img, cmd in workloads]

# Wait for all to complete
for job in jobs:
    while inspect_job(job_id=job.id).status.stage not in ("COMPLETED", "ERROR"):
        time.sleep(10)

スケジュールされたジョブ

CRON 式または定義済みのスケジュールを使って、ジョブを定期実行します。

MCP ツール：

# Schedule a UV script that runs every hour
hf_jobs("scheduled uv", {
    "script": "your_script.py",
    "schedule": "@hourly",
    "flavor": "cpu-basic"
})

# Schedule with CRON syntax
hf_jobs("scheduled uv", {
    "script": "your_script.py",
    "schedule": "0 9 * * 1",  # 9 AM every Monday
    "flavor": "cpu-basic"
})

# Schedule a Docker-based job
hf_jobs("scheduled run", {
    "image": "python:3.12",
    "command": ["python", "-c", "print('Scheduled!')"],
    "schedule": "@daily",
    "flavor": "cpu-basic"
})

Python API：

from huggingface_hub import create_scheduled_job, create_scheduled_uv_job

# Schedule a Docker job
create_scheduled_job(
    image="python:3.12",
    command=["python", "-c", "print('Running on schedule!')"],
    schedule="@hourly"
)

# Schedule a UV script
create_scheduled_uv_job("my_script.py", schedule="@daily", flavor="cpu-basic")

# Schedule with GPU
create_scheduled_uv_job(
    "ml_inference.py",
    schedule="0 */6 * * *",  # Every 6 hours
    flavor="a10g-small"
)

利用可能なスケジュール：

• @annually、@yearly - 年に1回
• @monthly - 月に1回
• @weekly - 週に1回
• @daily - 1日に1回
• @hourly - 1時間に1回
• CRON 式 - カスタムスケジュール（例：5分ごとの実行には "*/5 * * * *"）

スケジュールされたジョブを管理する：

# MCP Tool
hf_jobs("scheduled ps")                              # List scheduled jobs
hf_jobs("scheduled inspect", {"job_id": "..."})     # Inspect details
hf_jobs("scheduled suspend", {"job_id": "..."})     # Pause
hf_jobs("scheduled resume", {"job_id": "..."})      # Resume
hf_jobs("scheduled delete", {"job_id": "..."})      # Delete

管理用 Python API：

from huggingface_hub import (
    list_scheduled_jobs,
    inspect_scheduled_job,
    suspend_scheduled_job,
    resume_scheduled_job,
    delete_scheduled_job
)

# List all scheduled jobs
scheduled = list_scheduled_jobs()

# Inspect a scheduled job
info = inspect_scheduled_job(scheduled_job_id)

# Suspend (pause) a scheduled job
suspend_scheduled_job(scheduled_job_id)

# Resume a scheduled job
resume_scheduled_job(scheduled_job_id)

# Delete a scheduled job
delete_scheduled_job(scheduled_job_id)

Webhook：イベント発生時にジョブを実行する

Hugging Face リポジトリで変更が発生したときに、ジョブを自動的に実行します。

Python API：

from huggingface_hub import create_webhook

# Create webhook that triggers a job when a repo changes
webhook = create_webhook(
    job_id=job.id,
    watched=[
        {"type": "user", "name": "your-username"},
        {"type": "org", "name": "your-org-name"}
    ],
    domains=["repo", "discussion"],
    secret="your-secret"
)

仕組み：

1. Webhook は監視対象のリポジトリの変更を待ち受けます
2. トリガーされると、ジョブは WEBHOOK_PAYLOAD 環境変数を使って実行されます
3. スクリプトでペイロードを解析し、何が変更されたかを確認できます

ユースケース：

• 新しいデータセットがアップロードされたときに自動処理する
• モデルが更新されたときに推論を実行する
• コードが変更されたときにテストを実行する
• リポジトリのアクティビティに関するレポートを生成する

スクリプトで Webhook ペイロードにアクセスする：

import os
import json

payload = json.loads(os.environ.get("WEBHOOK_PAYLOAD", "{}"))
print(f"Event type: {payload.get('event', {}).get('action')}")

詳しくは、Webhook のドキュメントを参照してください。

一般的なワークロードのパターン

このリポジトリには、すぐに実行できる UV スクリプトが hf-jobs/scripts/ に用意されています。新しいテンプレートを作成する代わりに、これらを使うことを推奨します。

パターン 1：データセット → モデルの応答（vLLM）— scripts/generate-responses.py

機能：Hub データセット（チャットの messages または prompt 列）を読み込み、モデルのチャットテンプレートを適用し、vLLM で応答を生成して、出力データセットとデータセットカードを Hub にプッシュします。

**必要なもの：**GPU + 書き込みトークン（データセットをプッシュします）。

from pathlib import Path

script = Path("hf-jobs/scripts/generate-responses.py").read_text()
hf_jobs("uv", {
    "script": script,
    "script_args": [
        "username/input-dataset",
        "username/output-dataset",
        "--messages-column", "messages",
        "--model-id", "Qwen/Qwen3-30B-A3B-Instruct-2507",
        "--temperature", "0.7",
        "--top-p", "0.8",
        "--max-tokens", "2048",
    ],
    "flavor": "a10g-large",
    "timeout": "4h",
    "secrets": {"HF_TOKEN": "$HF_TOKEN"},
})

パターン 2：CoT Self-Instruct による合成データ — scripts/cot-self-instruct.py

機能：CoT Self-Instruct を使って合成プロンプトと回答を生成し、必要に応じて出力をフィルタリング（回答の一貫性／RIP）した後、生成したデータセットとデータセットカードを Hub にプッシュします。

**必要なもの：**GPU + 書き込みトークン（データセットをプッシュします）。

from pathlib import Path

script = Path("hf-jobs/scripts/cot-self-instruct.py").read_text()
hf_jobs("uv", {
    "script": script,
    "script_args": [
        "--seed-dataset", "davanstrien/s1k-reasoning",
        "--output-dataset", "username/synthetic-math",
        "--task-type", "reasoning",
        "--num-samples", "5000",
        "--filter-method", "answer-consistency",
    ],
    "flavor": "l4x4",
    "timeout": "8h",
    "secrets": {"HF_TOKEN": "$HF_TOKEN"},
})

パターン 3：データセットのストリーミング統計（Polars + HF Hub）— scripts/finepdfs-stats.py

**機能：**Hub から parquet を直接スキャンし（300GB のダウンロードは不要）、時系列統計を計算して、必要に応じて結果を Hub のデータセットリポジトリにアップロードします。

必要なもの：多くの場合 CPU で十分です。トークンが必要なのは --output-repo を指定してアップロードする場合のみです。

from pathlib import Path

script = Path("hf-jobs/scripts/finepdfs-stats.py").read_text()
hf_jobs("uv", {
    "script": script,
    "script_args": [
        "--limit", "10000",
        "--show-plan",
        "--output-repo", "username/finepdfs-temporal-stats",
    ],
    "flavor": "cpu-upgrade",
    "timeout": "2h",
    "env": {"HF_XET_HIGH_PERFORMANCE": "1"},
    "secrets": {"HF_TOKEN": "$HF_TOKEN"},
})

よくある障害

メモリ不足（OOM）

対処方法：

1. バッチサイズまたはデータチャンクのサイズを小さくします
2. データをより小さなバッチに分けて処理します
3. ハードウェアをアップグレードします：cpu → t4 → a10g → a100

ジョブのタイムアウト

対処方法：

1. ログで実際の実行時間を確認します
2. バッファーを設けてタイムアウトを延長します："timeout": "3h"
3. 実行速度が上がるようにコードを最適化します
4. データをチャンクに分けて処理します

Hub へのプッシュの失敗

対処方法：

1. トークンをシークレットに追加します：MCP では "$HF_TOKEN" を使用します（自動置換）。Python API では get_token() を使用します（実際のトークンを渡す必要があります）
2. スクリプト内のトークンを確認します：assert "HF_TOKEN" in os.environ
3. トークンの権限を確認します
4. リポジトリが存在するか、作成できることを確認します

依存関係の不足

対処方法： PEP 723 ヘッダーに追加します：

# /// script
# dependencies = ["package1", "package2>=1.0.0"]
# ///

認証エラー

対処方法：

1. ローカルで hf_whoami() が動作することを確認します
2. シークレット内のトークンを確認します — MCP："$HF_TOKEN"、Python API：get_token()（"$HF_TOKEN" は使用しません）
3. 再ログインします：hf auth login
4. トークンに必要な権限があることを確認します

トラブルシューティング

よくある問題：

• ジョブがタイムアウトする → タイムアウトを延長し、コードを最適化します
• 結果が保存されない → 永続化の方法を確認し、HF_TOKEN を確認します
• メモリ不足 → バッチサイズを小さくし、ハードウェアをアップグレードします
• インポートエラー → PEP 723 ヘッダーに依存関係を追加します
• 認証エラー → トークンを確認し、secrets パラメーターを確認します

参照： 完全なトラブルシューティングガイドについては、references/troubleshooting.md を参照してください

リソース

リファレンス（このスキル内）

• references/token_usage.md - トークンの使用方法に関する完全ガイド
• references/hardware_guide.md - ハードウェアの仕様と選び方
• references/hub_saving.md - Hub への永続化ガイド
• references/troubleshooting.md - よくある問題と解決方法

スクリプト（このスキル内）

• scripts/generate-responses.py - vLLM によるバッチ生成：データセット → 応答 → Hub にプッシュ
• scripts/cot-self-instruct.py - CoT Self-Instruct による合成データの生成とフィルタリング → Hub にプッシュ
• scripts/finepdfs-stats.py - Hub 上の finepdfs-edu parquet に対する Polars のストリーミング統計（プッシュは任意）

外部リンク

公式ドキュメント：

• HF Jobs ガイド - メインドキュメント
• HF Jobs CLI リファレンス - コマンドラインインターフェース
• HF Jobs API リファレンス - Python API の詳細
• ハードウェアの種類のリファレンス - 利用可能なハードウェア

関連ツール：

• UV スクリプトガイド - PEP 723 のインライン依存関係
• UV スクリプトの構成 - コミュニティによる UV スクリプト集
• HF Hub 認証 - トークンの設定
• Webhook ドキュメント - イベントトリガー

主なポイント

1. スクリプトをインラインで送信する - script パラメーターでは Python コードを直接指定できます。ユーザーから要望がない限り、ファイルに保存する必要はありません
2. ジョブは非同期で実行される - 完了を待ったり、ポーリングしたりしないでください。準備ができたらユーザーが確認できるようにします
3. 必ずタイムアウトを設定する - デフォルトの 30 分では不十分な場合があります。適切なタイムアウトを設定します
4. 必ず結果を永続化する - 環境は一時的なため、永続化しないとすべての作業が失われます
5. トークンを安全に使用する - MCP：secrets={"HF_TOKEN": "$HF_TOKEN"}、Python API：secrets={"HF_TOKEN": get_token()} — "$HF_TOKEN" が使えるのは MCP ツールのみです
6. 適切なハードウェアを選ぶ - 小さく始め、必要に応じてスケールアップします（ハードウェアガイドを参照）
7. UV スクリプトを使用する - Python ワークロードでは、インラインスクリプトを使った hf_jobs("uv", {...}) をデフォルトとして使用します
8. 認証を処理する - Hub の操作前にトークンが利用可能であることを確認します
9. ジョブを監視する - ジョブの URL とステータス確認コマンドを提示します
10. コストを最適化する - 適切なハードウェアを選び、適切なタイムアウトを設定します

クイックリファレンス：MCP ツール、CLI、Python API の比較

操作	MCP ツール	CLI	Python API
UV スクリプトを実行	hf_jobs("uv", {...})	hf jobs uv run script.py	run_uv_job("script.py")
Docker ジョブを実行	hf_jobs("run", {...})	hf jobs run image cmd	run_job(image, command)
ジョブを一覧表示	hf_jobs("ps")	hf jobs ps	list_jobs()
ログを表示	hf_jobs("logs", {...})	hf jobs logs <id>	fetch_job_logs(job_id)
ジョブをキャンセル	hf_jobs("cancel", {...})	hf jobs cancel <id>	cancel_job(job_id)
UV ジョブをスケジュール	hf_jobs("scheduled uv", {...})	hf jobs scheduled uv run SCHEDULE script.py	create_scheduled_uv_job()
Docker ジョブをスケジュール	hf_jobs("scheduled run", {...})	hf jobs scheduled run SCHEDULE image cmd	create_scheduled_job()
スケジュール済みジョブを一覧表示	hf_jobs("scheduled ps")	hf jobs scheduled ps	list_scheduled_jobs()
スケジュール済みジョブを削除	hf_jobs("scheduled delete", {...})	hf jobs scheduled delete <id>	delete_scheduled_job()