# 任务

请查阅 [HfApi](/docs/huggingface_hub/v2.4.0/zh/package_reference/hf_api#huggingface_hub.HfApi) 文档页面，以获取用于在 Hub 上管理 Jobs 的方法参考。

- 运行任务：[run_job()](/docs/huggingface_hub/v2.4.0/zh/package_reference/hf_api#huggingface_hub.HfApi.run_job)
- 获取日志：[fetch_job_logs()](/docs/huggingface_hub/v2.4.0/zh/package_reference/hf_api#huggingface_hub.HfApi.fetch_job_logs)
- 获取指标：[fetch_job_metrics()](/docs/huggingface_hub/v2.4.0/zh/package_reference/hf_api#huggingface_hub.HfApi.fetch_job_metrics)
- 检查任务：[inspect_job()](/docs/huggingface_hub/v2.4.0/zh/package_reference/hf_api#huggingface_hub.HfApi.inspect_job)
- 等待任务完成：[wait_for_job()](/docs/huggingface_hub/v2.4.0/zh/package_reference/hf_api#huggingface_hub.HfApi.wait_for_job)
- 列出任务：[list_jobs()](/docs/huggingface_hub/v2.4.0/zh/package_reference/hf_api#huggingface_hub.HfApi.list_jobs)
- 取消任务：[cancel_job()](/docs/huggingface_hub/v2.4.0/zh/package_reference/hf_api#huggingface_hub.HfApi.cancel_job)
- 运行 UV 任务：[run_uv_job()](/docs/huggingface_hub/v2.4.0/zh/package_reference/hf_api#huggingface_hub.HfApi.run_uv_job)
- 将本地目录同步以在 Job 中挂载：[sync_job_volume()](/docs/huggingface_hub/v2.4.0/zh/package_reference/hf_api#huggingface_hub.HfApi.sync_job_volume)

## 数据结构

### JobInfo[[huggingface_hub.JobInfo]]

#### huggingface_hub.JobInfo[[huggingface_hub.JobInfo]]

```python
huggingface_hub.JobInfo(**kwargs)
```

[源代码](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/_jobs_api.py#L186)

**参数：**

id (`str`) : 任务 ID。

created_at （`datetime` 或 `None`）：Job 创建的时间。

started_at (`datetime` 或 `None`)：Job 开始运行的时间。在 Job 仍处于调度状态时为 None。

finished_at (`datetime` 或 `None`)：任务完成的时间。当任务仍在调度或运行中时，该值为 None。

docker_image (`str` 或 `None`) : 用于该 Job 的 Docker Hub 上的 Docker 镜像。如果存在 space_id，则可以为 None。

space_id (`str` 或 `None`) : 用于该 Job 的 Hugging Face Spaces Docker 镜像。如果存在 docker_image，则可以为 None。

command (`list[str]` 或 `None`) : 任务的命令，例如 `["python", "-c", "print('hello world')"]`

arguments (`list[str]` 或 `None`) : 传递给命令的参数

environment (`dict[str]` 或 `None`) : 以字典形式表示的 Job 环境变量。

secrets (`dict[str]` 或 `None`) : 该 Job 的机密环境变量（已加密）。

flavor (`str` 或 `None`) : 硬件类型。有关可能的值，请参阅 `JobHardware`。例如 `"cpu-basic"`。

labels (`dict[str, str]` 或 `None`) : 要附加到任务上的标签（键值对）。

volumes (`list[Volume]` 或 `None`) : 挂载在作业容器中的卷（存储桶、模型、数据集、空间）。

status : (`JobStatus` 或 `None`)：作业的状态，例如 `JobStatus(stage="RUNNING", message=None)`。有关可能的阶段值，请参阅 [JobStage](/docs/huggingface_hub/v2.4.0/zh/package_reference/jobs#huggingface_hub.JobStage)。

durations (`JobDurations` 或 `None`)：Job 的耗时分解。在所有 Job 状态下均存在，包括 SCHEDULING。

owner : (`JobOwner` 或 `None`)：Job 的所有者，例如 `JobOwner(id="5e9ecfc04957053f60648a3e", name="lhoestq", type="user")`

initiator (`JobInitiator` 或 `None`)：触发该 Job 的原因，例如对于由 cron 触发的运行，值为 `JobInitiator(type="scheduled-job", id="...")`。

expose_urls (`list[str]` 或 `None`) : 用于访问 Job 暴露端口的公共 URL（每个暴露端口对应一个），例如 `["https://687fb701029421ae5549d998--8000.hf.jobs"]`。如果没有暴露端口，则为 `None`。除非端口是公开的，否则访问 URL 需要一个具有 Job 命名空间读取权限的 HF token。

ssh_url (`str` 或 `None`)：Job 的 SSH 端点，例如 `"ssh://687fb701029421ae5549d998@ssh.hf.jobs"`。仅当 Job 以 `ssh=True` 启动时才会存在。连接需要对 Job 的命名空间具有写入权限，并在 Hub 上注册 SSH 公钥（https://huggingface.co/settings/keys）。

network (`JobNetwork` 或 `None`)：Job 加入的网络组及其声明的别名，例如 `JobNetwork(group="train", aliases=["master"])`。如果 Job 启动时未指定 `network_group=`，则为 `None`。

retry (`int` 或 `None`) : 为 Job 配置的重试次数 (`attempts - 1`)。

expose (`list[int]` 或 `None`) : 通过 Jobs 代理公开的所有端口，包括公共端口。

expose_public (`list[int]` 或 `None`) : 无需身份验证即可访问的已暴露端口。

包含有关 Job 的信息。

示例：

```python
>>> from huggingface_hub import run_job
>>> job = run_job(
...     image="python:3.12",
...     command=["python", "-c", "print('Hello from the cloud!')"]
... )
>>> job
JobInfo(id='687fb701029421ae5549d998', created_at=datetime.datetime(2025, 7, 22, 16, 6, 25, 79000, tzinfo=datetime.timezone.utc), started_at=datetime.datetime(2025, 7, 22, 16, 6, 31, 79000, tzinfo=datetime.timezone.utc), finished_at=None, docker_image='python:3.12', space_id=None, command=['python', '-c', "print('Hello from the cloud!')"], arguments=[], environment={}, secrets={}, flavor='cpu-basic', labels=None, status=JobStatus(stage='RUNNING', message=None), durations=JobDurations(scheduling_secs=6, running_secs=2, total_secs=8), owner=JobOwner(id='5e9ecfc04957053f60648a3e', name='lhoestq', type='user'), initiator=JobInitiator(type='user', id='5e9ecfc04957053f60648a3e', name='lhoestq'), endpoint='https://huggingface.co', url='https://huggingface.co/jobs/lhoestq/687fb701029421ae5549d998')
>>> job.id
'687fb701029421ae5549d998'
>>> job.url
'https://huggingface.co/jobs/lhoestq/687fb701029421ae5549d998'
>>> job.status.stage
'RUNNING'
```

### JobOwner[[huggingface_hub.JobOwner]]

#### huggingface_hub.JobOwner[[huggingface_hub.JobOwner]]

```python
huggingface_hub.JobOwner(id: str, name: str, type: str)
```

[源代码](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/_jobs_api.py#L116)

### JobNetwork[[huggingface_hub.JobNetwork]]

#### huggingface_hub.JobNetwork[[huggingface_hub.JobNetwork]]

```python
huggingface_hub.JobNetwork(**kwargs)
```

[源代码](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/_jobs_api.py#L123)

**参数：**

group (`str`) : 网络组的名称，即传递给 `network_group=` 的值。

aliases (`list[str]`) : 该组中 Job 所声明的别名，即传递给 `network_aliases=` 的值。若未指定则为空。

网络组 a Job 已加入。

### JobStage[[huggingface_hub.JobStage]]

#### huggingface_hub.JobStage[[huggingface_hub.JobStage]]

```python
huggingface_hub.JobStage(value, names = None, module = None, qualname = None, type = None, start = 1)
```

[源代码](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/_jobs_api.py#L71)

Hub 上 Job 可能处于的阶段枚举。

Value 可以与字符串进行比较：
```py
assert JobStage.COMPLETED == "COMPLETED"
```

可能的值包括：`COMPLETED`、`CANCELED`、`ERROR`、`DELETED`、`SCHEDULING`、`RUNNING`。取自 https://github.com/huggingface/moon-landing/blob/main/server/job_types/JobInfo.ts#L61（私有 URL）。

### JobStatus[[huggingface_hub.JobStatus]]

#### huggingface_hub.JobStatus[[huggingface_hub.JobStatus]]

```python
huggingface_hub.JobStatus(stage: JobStage, message: str | None, expose_urls: list[str] | None, ssh_url: str | None)
```

[源代码](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/_jobs_api.py#L108)

### 卷[[huggingface_hub.Volume]]

#### huggingface_hub.Volume[[huggingface_hub.Volume]]

```python
huggingface_hub.Volume(**kwargs)
```

[源代码](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/_space_api.py#L128)

**参数：**

type (`str`) : 卷的类型：`"bucket"`、`"model"`、`"dataset"` 或 `"space"`。

source (`str`) : 源标识符，例如 `"username/my-bucket"` 或 `"username/my-model"`。

mount_path (`str`) : 容器内的挂载路径，例如 `"/data"`。必须以 `/` 开头。

revision (`str` 或 `None`)：Git 修订版本（仅适用于仓库，默认为 `"main"`）。

read_only (`bool` 或 `None`)：只读挂载。对于仓库强制为 `True`，对于存储桶默认为 `False`。

path (`str` 或 `None`) : 要挂载的存储桶/仓库内的子文件夹前缀，例如 `"path/to/dir"`。

描述要在 Space 或 Job 容器中挂载的卷。

#### to_dict[[huggingface_hub.Volume.to_dict]]

```python
to_dict()
```

[源代码](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/_space_api.py#L164)

将其序列化为 Hub API 预期的 JSON 负载。

#### to_uri[[huggingface_hub.Volume.to_uri]]

```python
to_uri()
```

[源代码](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/_space_api.py#L179)

以 CLI 所期望的格式，将卷返回为 HF 挂载 URI。