# ジョブの管理

## ジョブのリスト表示

Jobsページまたは組織のJobsページ（ユーザー/組織ページ > settings > Jobs）で、Jobsのリストを確認してください:

Hugging Face CLIでも利用できます。`hf jobs ps`で実行中のJobsのリストを表示し、`-a`オプションを指定するとすべてのJobsを表示できます:

```bash
>>> hf jobs ps
JOB ID       IMAGE/SPACE      COMMAND     CREATED             STATUS  
------------ ---------------- ----------- ------------------- ------- 
69402ea6c... ghcr.io/astra... uv run p... 2025-12-15 15:52:06 RUNNING
>>> hf jobs ps -a
JOB ID       IMAGE/SPACE COMMAND         CREATED             STATUS    
------------ ---------- --------------- ------------------- --------- 
69402ea6c... ghcr.io... uv run pytho... 2025-12-15 15:52:06 RUNNING   
693b06b8c... ghcr.io... uv run pytho... 2025-12-11 18:00:24 CANCELED  
693b069fc... ghcr.io... uv run pytho... 2025-12-11 17:59:59 ERROR     
693aef401... ghcr.io... uv run pytho... 2025-12-11 16:20:16 COMPLETED 
693aee76c... ubuntu     echo Hello f... 2025-12-11 16:16:54 COMPLETED 
693ae8e3c... python:... python -c pr... 2025-12-11 15:53:07 COMPLETED
```

組織の`namespace`を指定して、組織配下のJobsをリスト表示します:

```bash
>>> hf jobs ps --namespace <my-org-name>
```

## ジョブをフィルタリング

最もよく使用されているラベルは、Jobsリストの上部に、各ラベルを使用しているJobsの数とともに表示されます。クリックするとそのラベルでフィルタリングでき、任意の`key=value`ラベルを入力することもできます。

CLIでは、`--status`でステータス、`--label key=value`でラベルを指定してフィルタリングできます。`--label`を繰り返し指定することで、複数のラベルを同時に指定できます:

```bash
# Jobs that ended in error
>>> hf jobs ps --status error

# Running or scheduling Jobs with a given label
>>> hf jobs ps --status running,scheduling --label env=prod

# All Jobs (any status) that have both labels
>>> hf jobs ps -a --label model=Qwen3-06B --label dataset=Capybara

# A label added without a value (`--label fine-tuning`) is matched with a trailing "="
>>> hf jobs ps -a --label fine-tuning=
```

`--name`で名前を指定してフィルタリングできます。`--name`は`--label name=<name>`のショートカットです。例えば、名前付きJobのすべての実行をリスト表示するには:

```bash
>>> hf jobs ps -a --name daily-report
JOB_ID      NAME         IMAGE/SPACE COMMAND      CREATED      STATUS    RUNTIME
----------- ------------ ----------- ------------ ------------ --------- -------
6a9042c2... daily-report python:3.12 python -c... 2026-08-2... COMPLETED 0s     
6a904162... daily-report python:3.12 python -c... 2026-08-2... CANCELED  --     
```

> [!TIP]
> デフォルトでは`hf jobs ps`は実行中およびスケジューリング中のJobsを表示します。すべてのステータスを表示するには`-a`を使用します。`-a`は`--status`と併用できません。

## リソース使用量の監視

実行中のJobsのCPU、メモリ、ネットワーク、GPU（該当する場合）の使用状況のスナップショットを取得するには、`hf jobs stats`を使用します：

```bash
>>> hf jobs stats
JOB ID                   CPU % NUM CPU MEM % MEM USAGE        NET I/O         GPU UTIL % GPU MEM % GPU MEM USAGE   
------------------------ ----- ------- ----- ---------------- --------------- ---------- --------- --------------- 
695e83c5d2f3efac77e8cf18 8%    12.0    7.18% 10.9GB / 152.5GB 0.0bps / 0.0bps 100%       31.92%    25.9GB / 81.2GB
```

特定のJobの統計のみを表示するには、1つ以上のJob IDを指定します:

```bash
>>> hf jobs stats [job-ids]...
```

`-f` を使用して、Jobs が完了するまで統計をライブで追跡します:

```bash
>>> hf jobs stats -f [job-ids]...
```

## ジョブの検査

Jobのステータスログは、Jobページで確認できます:

Alternatively using the CLI

```bash
>>> hf jobs inspect 693994e21a39f67af5a41ad0 
[
    {
        "id": "693994e21a39f67af5a41ad0",
        "created_at": "2025-12-10 15:42:26.835000+00:00",
        "docker_image": "ghcr.io/astral-sh/uv:python3.12-bookworm",
        "space_id": null,
        "command": ["bash", "-c", "python -c \"import urllib.request; import os; from pathlib import Path; o = urllib.request.build_opener(); o.addheaders = [(\\\"Authorization\\\", \\\"Bearer \\\" + os.environ[\\\"UV_SCRIPT_HF_TOKEN\\\"])]; Path(\\\"/tmp/script.py\\\").write_bytes(o.open(os.environ[\\\"UV_SCRIPT_URL\\\"]).read())\" && uv run --with trl /tmp/script.py"],
        "arguments": [],
        "environment": {"UV_SCRIPT_URL": "https://huggingface.co/datasets/lhoestq/hf-cli-jobs-uv-run-scripts/resolve/728cc5682eb402d7ffe66a2f6f97645b34cb08dd/train.py"},
        "secrets": ["HF_TOKEN", "UV_SCRIPT_HF_TOKEN"],
        "flavor": "a100-large",
        "status": {"stage": "COMPLETED", "message": null},
        "owner": {"id": "5e9ecfc04957053f60648a3e", "name": "lhoestq", "type": "user"},
        "endpoint": "https://huggingface.co",
        "url": "https://huggingface.co/jobs/lhoestq/693994e21a39f67af5a41ad0"
    }
]
```

そしてログについては

```bash
>>> hf jobs logs 693994e21a39f67af5a41ad0
Downloading nvidia-cuda-nvrtc-cu12 (84.0MiB)
Downloading numpy (15.8MiB)
Downloading nvidia-cuda-cupti-cu12 (9.8MiB)
Downloading tokenizers (3.1MiB)
Downloading nvidia-cusolver-cu12 (255.1MiB)
Downloading nvidia-cufft-cu12 (184.2MiB)
Downloading transformers (11.4MiB)
Downloading setuptools (1.1MiB)
... 
```

組織の`namespace`を指定して、組織配下の Job を確認します:

```bash
hf jobs inspect --namespace <my-org-name> <job_id>
hf jobs logs --namespace <my-org-name> <job_id>
```

## ジョブの完了を待機

`hf jobs wait` を使用すると、1 つ以上の Job が終端状態（`COMPLETED`、`CANCELED`、`ERROR` または `DELETED`）に達するまでブロックします。すべての Job が正常に完了した場合のみ終了コード `0` を返し、それ以外の場合は非ゼロのコードを返します。シェルスクリプトや CI でのステップの連鎖に便利です。

```bash
# Wait for a single Job
>>> hf jobs wait 693994e21a39f67af5a41ad0

# Wait for several Jobs at once (all must be in the same namespace)
>>> hf jobs wait <job_id_1> <job_id_2>

# Wait for every currently running Job
>>> hf jobs ps -q | xargs hf jobs wait
```

`--timeout` で最大待機時間を設定します（`s`、`m`、`h`、`d` を指定可能）:

```bash
>>> hf jobs wait --timeout 30m 693994e21a39f67af5a41ad0
```

`hf jobs wait` は Job が失敗したときにゼロ以外の終了コードを返すため、`&&` でチェーンできます。非デタッチの `hf jobs run`（または `hf jobs uv run`）はすでにブロックし、失敗時にゼロ以外の終了コードで終了するため、明示的な wait はデタッチされた Job（`-d`）またはバッチの待機が必要な場合のみです：

```bash
>>> hf jobs wait 693994e21a39f67af5a41ad0 && echo "job completed successfully"
```

## 結果を永続化

Jobが終了すると、そのJobのファイルシステムは削除されます。Jobが終了する前に、保持したいデータは永続的なストレージに書き出してください。

- **中間成果物、チェックポイント、ログ → Storage Bucket ボリューム。**バケットをマウントし、マウントパス配下に出力を書き込みます。例については[Volumes](./jobs-configuration#volumes)を参照してください。ジョブの作成時に Hugging Face のアイデンティティでボリュームマウントが認可されるため、スクリプトがそれらに書き込む際にトークンは不要です。

- **最終モデルとデータセット → Hub リポジトリにプッシュ。**ジョブには、`--secrets HF_TOKEN` のように渡さない限り Hugging Face トークンはありません（この形式は、ログイン中のトークンを自動的に解決します）。スクリプトが `push_to_hub()` または `create_repo()` を呼び出す場合、トークンに書き込みアクセス権があることを確認してください（ファイングレイン トークンは、リポジトリの書き込みと作成権限が必要です）。よくある失敗パターンとして、数時間の計算を完了したジョブが、最終アップロード時にトークンが書き込めないためエラーになるケースがあります。計算は完了していますが、結果は保存されません。

- **主要な結果をログに出力します。** Job のログは Job が終了した後も保持され、`hf jobs logs <job-id>` を使用していつでも取得できます。最終的なメトリクスを stdout に出力することで、アップロード手順が失敗した場合でも復元可能になります。

Job が完了した後、出力が実際に保存されていることを確認してください（`hf buckets list` を使用して確認できます）。`COMPLETED` ステータスは、コマンドが正常に終了したことを示すものであり、ファイルが想定した場所に永続化されたことを保証するものではありません。

## ジョブのデバッグ

Jobにエラーが発生した場合、Jobページで確認できます

ジョブページのステータスメッセージとログを確認して、何が問題だったかを見てください。

ジョブが失敗する直前に何が起きたかを確認するには、ログの最後の数行を参照することもできます。これはジョブのページで確認するか、CLIを使用して確認できます。

```bash
>>> hf jobs logs 69405cf51a39f67af5a41f29 | tail -n 10     
 Downloaded nvidia-cudnn-cu12
 Downloaded torch
Installed 66 packages in 226ms
Generating train split: 100%|██████████| 15806/15806 [00:00<00:00, 73330.17 examples/s]
Generating test split: 100%|██████████| 200/200 [00:00<00:00, 45427.32 examples/s]
Traceback (most recent call last):
  File "/tmp/script.py", line 7, in <module>
    train_dataset=train_dataset,
                  ^^^^^^^^^^^^^
NameError: name 'train_dataset' is not defined. Did you mean: 'load_dataset'?
```

ローカルのUVまたはDockerセットアップを使用して、ジョブをローカルでデバッグします:

* `hf jobs uv run ...` -> `uv run ...`
* `hf jobs run ...` -> `docker run ...`

ステータスメッセージに「Job timeout」と表示される場合があります。これは、Jobがタイムアウト（デフォルトは30分）前に完了しなかったため、停止されたことを意味します。この場合、CLIで`--timeout`を使用して、より長いタイムアウトを指定する必要があります。例:

```bash
hf jobs uv run --timeout 3h ...
```

## ジョブを再実行する

`hf jobs rerun` を使用すると、既存の Job の保存済み設定（シークレットやハードウェアの flavor を含む）で新しい Job を開始できます。

```bash
>>> hf jobs rerun <job_id>
```

新しいJobには独自のIDが割り当てられます。Pythonでは`rerun_job`を使用します。

## ジョブのキャンセル

Jobページにある「Cancel」ボタンを使用して、Jobをキャンセルします：

または CLI で:

```bash
hf jobs cancel 693b06b8c67c9f186cfe239e
```

組織の`namespace`を指定して、組織配下のJobをキャンセルします:

```bash
hf jobs cancel --namespace <my-org-name> <job_id>
```

## MacOSメニューバー

MacOSの[`hfjobs-menubar`](https://github.com/drbh/hfjobs-menubar)クライアントで、Jobsのリストを確認できます:

Jobs の情報を取得し、ログとリソース使用状況の統計を監視します: