# 沙盒

> [!NOTE]
> Sandbox API 目前处于实验阶段。其 API 和行为可能会在不另行通知的情况下发生变更。共享沙箱适用于同一信任边界内的工作负载；对于互不信任的工作负载，请使用专用沙箱。

查看 [沙箱指南](../guides/sandbox) 以了解如何使用它们。

## 沙盒[[huggingface_hub.Sandbox]]

#### huggingface_hub.Sandbox[[huggingface_hub.Sandbox]]

```python
huggingface_hub.Sandbox(id: str, server: _SandboxServer, local_id: str | None, owns_sandbox: bool, owns_server: bool, sandbox_token: str | None = None)
```

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

运行在 Hugging Face Jobs 上的独立云机器。

> [!NOTE]
> Sandbox API 目前处于实验阶段。其 API 和行为可能会在不另行通知的情况下发生变化。

使用 [Sandbox.create()](/docs/huggingface_hub/v2.4.0/zh/package_reference/sandbox#huggingface_hub.Sandbox.create) 创建一个专用的沙箱（每个沙箱对应一个任务），或者从 [SandboxPool](/docs/huggingface_hub/v2.4.0/zh/package_reference/sandbox#huggingface_hub.SandboxPool) 中获取多个低成本的共享沙箱。

使用 [Sandbox.connect()](/docs/huggingface_hub/v2.4.0/zh/package_reference/sandbox#huggingface_hub.Sandbox.connect) 可从任意位置重新连接到正在运行的沙箱。将其用作上下文管理器，以便在退出时终止它：

```python
>>> from huggingface_hub import Sandbox
>>> with Sandbox.create(image="python:3.12") as sbx:
...     print(sbx.run("python --version").stdout)
```

#### 关闭[[huggingface_hub.Sandbox.close]]

```python
close()
```

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

在不终止沙箱的情况下释放本地 HTTP 客户端。幂等。

对于池沙箱，此操作为空操作（客户端属于池的主机）。

#### 连接[[huggingface_hub.Sandbox.connect]]

```python
connect(sandbox_id: str, namespace: str | None = None, token: str | None = None)
```

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

仅使用其 id，即可从任意位置重新连接到正在运行的沙箱。

#### 创建[[huggingface_hub.Sandbox.create]]

```python
create(image: str = 'python:3.12', flavor: str = 'cpu-basic', idle_timeout: int | float | str | None = 600, env: dict[str, typing.Any] | None = None, secrets: dict[str, typing.Any] | None = None, volumes: typing.Optional[typing.List[huggingface_hub._space_api.Volume]] = None, namespace: str | None = None, forward_hf_token: bool = False, labels: dict[str, str] | None = None, start_timeout: float = 120.0, token: str | None = None)
```

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

**参数：**

image (`str`，*可选*，默认为 `"python --3.12"`)：任何包含 `/bin/sh` 的 Docker 镜像（Docker Hub 或 `hf.co/spaces/...`）。

flavor (`str`，*可选*，默认为 `"cpu-basic"`)：硬件类型，例如 `"cpu-basic"`、`"a10g-small"`。请参阅 `hf jobs hardware`。

idle_timeout (`int` 或 `float` 或 `str`，*可选*，默认为 `600`) : 在此时长内无活动（无 API 调用，无运行中的进程）后自动关闭。默认值为 10 分钟；传入 `None` 可禁用此功能。请注意，*前台*命令目前不计入活动，因此如果单个 `run()` 命令执行时间超过该时长且没有其他 API 流量，其沙箱可能会被关闭——对于耗时较长的单个命令，请增加超时时间（或传入 `None`）。

env (`dict[str, Any]`，*可选*)：沙箱中可用的环境变量。

secrets (`dict[str, Any]`，*可选*)：机密环境变量（在服务器端加密）。

volumes (`List[Volume]`, *可选*) : 要挂载的 HF 仓库/存储桶，参见 [Volume](/docs/huggingface_hub/v2.4.0/zh/package_reference/jobs#huggingface_hub.Volume)。

namespace (`str`, *可选*) : 要运行在其中的用户或组织命名空间（默认为当前用户）。

forward_hf_token (`bool`，*可选*，默认为 `False`)：如果为 True，您的 HF token 将作为 `HF_TOKEN` 注入（需主动选择）。

labels (`dict[str, str]`, *可选*) : 附加到底层 HF Job 的标签。

start_timeout (`float`, *可选*, 默认值为 `120.0`) : 等待沙箱就绪的最大秒数。

token (`str`, *可选*) : HF 令牌覆盖。

创建一个专用的沙箱（一个 HF Job），并阻塞等待其就绪（在 cpu-basic 上约需 7 秒）。

每个沙箱都是一个完全隔离的虚拟机，因此它是 GPU 工作负载或不可信代码的正确选择。若要并行分发大量低成本的 CPU 沙箱，请使用 [SandboxPool](/docs/huggingface_hub/v2.4.0/zh/package_reference/sandbox#huggingface_hub.SandboxPool)。

任务以固定的 24 小时最大生命周期运行；`idle_timeout` 才是真正的关键——空闲的沙箱会在那之前自行关闭。

该镜像只需要 `/bin/sh`。如果可用，沙箱服务器会在启动时通过 `wget`/`curl` 下载；否则，将从始终挂载的服务器存储桶中读取（这会使冷启动时间增加约 2-3 秒，因此提供 `wget`/`curl` 可保持快速启动）。

#### 进程[[huggingface_hub.Sandbox.processes]]

```python
processes()
```

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

列出此沙箱中的后台进程。

返回通过 [Sandbox.run()](/docs/huggingface_hub/v2.4.0/zh/package_reference/sandbox#huggingface_hub.Sandbox.run)`(..., background=True)` 启动的进程；使用 [SandboxProcess.kill()](/docs/huggingface_hub/v2.4.0/zh/package_reference/sandbox#huggingface_hub.SandboxProcess.kill) 停止其中一个。最近完成的进程仍会保留在列表中（其 `running=False` 并带有 `exit_code`）；服务器会保留有限数量的此类进程，因此运行了数千条短命令的沙箱不会列出所有进程。

#### proxy_url_for[[huggingface_hub.Sandbox.proxy_url_for]]

```python
proxy_url_for(port: int | str, path: str = '/', scheme: str = 'https://')
```

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

**参数：**

port (`int` 或 `str`)：内部服务器监听的端口（池：unix socket 的 `<port>`）。

path (`str`，*可选*，默认为 `"/"`)：内部服务器上要指向的路径，例如 `"/ws"`。

scheme (`str`，*可选*，默认为 `"https --//"`)：用于构建链接的 URL 协议。默认为 `"https://"`；对于 WebSocket 客户端，请传入 `"wss://"`（代理与协议无关，因此只有客户端侧的协议会发生变化）。

**返回：** `str`

类似 `https://<job_id>--49983.hf.jobs/v1/.../proxy/8000/ws` 的 URL（或 `wss://...`，配合 `scheme="wss://"`）。

一个通过代理指向在此沙箱*内部*运行的服务器的公共 URL。

对返回的 URL 发出的请求将由作业内的沙箱服务器转发到您在沙箱中启动的 `port` 端口上的服务器，包括 WebSocket（`ws(s)://`）升级和流式响应。请将其与 `proxy_headers` 配合使用以实现身份验证。

沙箱必须监听`port`的方式：

- **池化 / 共享沙箱**：无法绑定 TCP 端口（Landlock），因此请在 `$SBX_PROXY_DIR/<port>.sock` 处绑定一个 **unix socket**（`SBX_PROXY_DIR` 环境变量在每个沙箱中均已设置）。例如 `uvicorn app:app --uds $SBX_PROXY_DIR/8000.sock`。
- **专用沙箱**：在 `127.0.0.1:<port>` 上绑定一个普通的 TCP 端口。（你也可以通过作业代理直接暴露该端口，而无需经过此处。）

示例：
```python
>>> url = sandbox.proxy_url_for(8000, "/ws", scheme="wss://")
>>> import websockets
>>> async with websockets.connect(url, additional_headers=sandbox.proxy_headers) as ws:
...     await ws.send("hello")
```

#### 运行[[huggingface_hub.Sandbox.run]]

```python
run(cmd: typing.Union[str, typing.List[str]], shell: bool | None = None, env: dict[str, typing.Any] | None = None, cwd: str | None = None, timeout: float | None = None, stdin: str | None = None, on_stdout: typing.Optional[typing.Callable[[str], NoneType]] = None, on_stderr: typing.Optional[typing.Callable[[str], NoneType]] = None, check: bool = True, capture_output: bool = True, background: bool = False)
```

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

**参数：**

cmd (`str` 或 `List[str]`)：一个 shell 命令字符串（通过 `/bin/sh -c` 运行）或一个 argv 列表（直接执行）。

shell (`bool`, *可选*) : 强制指定执行模式，而不是根据 `cmd` 的类型进行推断。`True` 会通过 `/bin/sh -c` 运行，并要求 `cmd` 为字符串；`False` 会直接执行 `cmd`，并要求其为 argv 列表。`None`（默认值）根据类型进行推断。请显式设置该参数以避免由类型引发的陷阱（例如 `["echo hi"]` 被当作名为 `"echo hi"` 的单个程序执行）。

env (`dict[str, Any]`, *可选*) : 此命令的额外环境变量。

cwd (`str`, *可选*) : 工作目录。

timeout (`float`, *可选*) : 在此秒数后终止命令（整个进程组）。

stdin (`str`, *可选*) : 要写入命令标准输入的数据。

on_stdout (`Callable[[str], None]`，*可选*)：在标准输出块到达时调用的回调。

on_stderr (`Callable[[str], None]`，*可选*)：在 stderr 数据块到达时调用的回调。

check (`bool`，*可选*，默认为 `True`)：如果为 True，则在退出码非零时引发 `SandboxCommandError`。

capture_output (`bool`，*可选*，默认为 `True`)：如果为 True，则将 stdout/stderr 累积到返回的结果中。如果只需要 `on_stdout`/`on_stderr`，请传入 `False`：此时输出会交给回调函数处理并被丢弃，因此产生数 GB 输出的命令无需全部装入内存。在这种情况下，`result.stdout`/`result.stderr` 为空。

background (`bool`，*可选*，默认为 `False`)：如果为 True，则以分离模式启动命令，并立即返回一个 [SandboxProcess](/docs/huggingface_hub/v2.4.0/zh/package_reference/sandbox#huggingface_hub.SandboxProcess)，而不是等待其完成并返回一个 [SandboxCommandResult](/docs/huggingface_hub/v2.4.0/zh/package_reference/sandbox#huggingface_hub.SandboxCommandResult)。

在沙箱中运行命令并等待其完成，同时实时流式传输输出。

设置 `background=True` 后，命令将以分离方式启动，`run` 会立即返回一个 [SandboxProcess](/docs/huggingface_hub/v2.4.0/zh/package_reference/sandbox#huggingface_hub.SandboxProcess)，而不会等待其执行完毕——这对于服务器和其他长时间运行的进程非常实用。之后可以使用 [Sandbox.processes()](/docs/huggingface_hub/v2.4.0/zh/package_reference/sandbox#huggingface_hub.Sandbox.processes) 列出这些进程，并使用 [SandboxProcess.kill()](/docs/huggingface_hub/v2.4.0/zh/package_reference/sandbox#huggingface_hub.SandboxProcess.kill) 停止其中一个。流式/仅等待选项（`timeout`、`stdin`、`on_stdout`、`on_stderr`、`check`）在该模式下不适用。

返回：一个 [SandboxCommandResult](/docs/huggingface_hub/v2.4.0/zh/package_reference/sandbox#huggingface_hub.SandboxCommandResult)（包含 `exit_code`、`stdout`、`stderr`、`duration_ms`），或者当 `background=True` 时返回一个 [SandboxProcess](/docs/huggingface_hub/v2.4.0/zh/package_reference/sandbox#huggingface_hub.SandboxProcess)。

## SandboxPool[[huggingface_hub.SandboxPool]]

#### huggingface_hub.SandboxPool[[huggingface_hub.SandboxPool]]

```python
huggingface_hub.SandboxPool(image: str = 'python:3.12', flavor: str = 'cpu-basic', sandboxes_per_host: int = 50, warm_up: int = 1, max_hosts: int | None = None, name: str | None = None, idle_timeout: int | float | str | None = 600, namespace: str | None = None, start_timeout: float = 120.0, adopt_hosts: str = 'own', token: str | None = None, _connect_mode: bool = False)
```

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

一组共享的“host”作业，每个作业都包含许多由 landlock 隔离的沙箱。

> [!WARNING]
> Sandbox API 目前处于实验阶段。其 API 和行为可能会在不另行通知的情况下发生变化。
>
> **池化沙箱适用于同一信任边界内的工作负载。** 池化沙箱是共享虚拟机内的一个 uid 加上一组 Landlock 规则集——而非独立的虚拟机——并且主机上的每个沙箱都共享该主机的身份验证令牌及其特权控制平面。使用池化沙箱可以低成本地并行运行*您自己的*代码。对于相互不信任的工作负载，请使用[Sandbox.create()](/docs/huggingface_hub/v2.4.0/zh/package_reference/sandbox#huggingface_hub.Sandbox.create)，它将为每个工作负载提供独立的虚拟机。具体的局限性列在沙箱概念指南的“已知限制”部分。

一台主机对应一个计费的 HF Job（即一台虚拟机）；它运行沙箱服务器，并复用最多 `sandboxes_per_host` 个轻量级沙箱，这些沙箱之间通过 uid 和 Landlock LSM 实现相互隔离。这使得大规模扇出既经济（虚拟机成本由所有沙箱分摊）又快速（主机预热后，创建一个沙箱仅需约一次代理往返）。最适合大量并行 CPU 沙箱场景，例如 RL 推演；若需 GPU 支持，或需在互不信任的工作负载之间实现强 VM 级隔离，请改用 [Sandbox.create()](/docs/huggingface_hub/v2.4.0/zh/package_reference/sandbox#huggingface_hub.Sandbox.create)。

构造函数会预先配置 `warm_up` 个主机（默认为 1），并阻塞直到它们就绪；之后，随着沙箱请求的增加，会按需配置更多主机，并且所有

在调用 `close()` 时（或在空闲时，通过 `idle_timeout`）会被拆除。用户无需管理任务：

```python
>>> from huggingface_hub import SandboxPool
>>> with SandboxPool(image="python:3.12", flavor="cpu-basic", warm_up=2) as pool:
...     boxes = [pool.create() for _ in range(100)]   # packed across the warm hosts
...     print(boxes[0].run("echo hi").stdout)
hi
```

`create()` 每次只创建 **一个** 沙箱：它会先复用仍有空闲容量的主机，然后再启动新主机，因此随着任务到达按需扩展。为了避免前几次调用出现冷启动，可以使用 `warm_up`（或 `warm`）预先配置主机。通过作业标签可以发现预热主机，因此复用功能也适用于 **跨进程** 场景（使用相同 `image`/`flavor`/`name` 的新池会连接到

是之前运行留下的）：

```python
>>> pool = SandboxPool(image="python:3.12")
>>> sbx = pool.create()    # finds a warm host (here or in another process), else boots one
```

#### 关闭[[huggingface_hub.SandboxPool.close]]

```python
close()
```

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

释放池。幂等。

对于我们创建的池，这会终止所有主机任务（因此也会终止它们的所有沙箱）。对于通过 `connect()` 连接的句柄，它仅释放本地 HTTP 客户端：共享主机可能正在为其他客户端提供服务，因此——与 [Sandbox.connect()](/docs/huggingface_hub/v2.4.0/zh/package_reference/sandbox#huggingface_hub.Sandbox.connect) 类似——退出 `with` 块时不应将其关闭。请显式使用 `hf sandbox pool delete <id>` 来终止已连接池的主机。

只有主机上*由此处理程序启动*的进程会被取消。通过标签发现的主机可能正在为其他进程的沙箱提供服务，因此会被释放而不是终止。

如果无法取消主机任务，则引发 `SandboxError`，并指明仍在运行的任务——这些任务将继续计费，且其缓存条目会被保留，以便保持可发现性。当通过 `__exit__` 到达 `close()` 且已有异常正在传播时，该失败会被记录到日志中，以免掩盖原始错误。

#### 连接[[huggingface_hub.SandboxPool.connect]]

```python
connect(pool_id: str, namespace: str | None = None, adopt_hosts: str = 'own', token: str | None = None)
```

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

**参数：**

pool_id (`str`) : 池首次创建时返回的 id。

namespace (`str`, *可选*) : 用于搜索池主机的命名空间（默认为您自己的命名空间）。

adopt_hosts (`str`, *可选*, 默认为 `"own"`) : 可以附加到哪些主机。参见 [SandboxPool](/docs/huggingface_hub/v2.4.0/zh/package_reference/sandbox#huggingface_hub.SandboxPool)。重新附加到由命名空间内其他成员启动的主机组成的池需要 `"namespace"`。

token (`str`, *可选*) : HF 令牌覆盖。

通过 ID 从任意机器重新连接到正在运行的池——无需本地状态。

查找带有 `pool_id` 标签的运行中主机，并根据该主机作业的规格和环境变量重建池的配置（image/flavor/density/host-idle），返回一个可直接调用 `create()` 以创建更多沙箱的 [SandboxPool](/docs/huggingface_hub/v2.4.0/zh/package_reference/sandbox#huggingface_hub.SandboxPool)——它会优先将沙箱打包到运行中的主机上，若主机已满则启动一个副本（配置相同）。

如果未找到正在运行的主机，则引发 `SandboxError`（当池中的所有主机都消失——无论是因空闲超时还是被终止——时，该池即停止存在）。

#### 创建[[huggingface_hub.SandboxPool.create]]

```python
create(env: dict[str, typing.Any] | None = None, idle_timeout: int | float | str | None = 600, forward_hf_token: bool = False)
```

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

**参数：**

env (`dict[str, Any]`, *可选*) : 此沙箱的环境变量（每个沙箱都有自己独立的环境变量）。

idle_timeout (`int` 或 `float` 或 `str`，*可选*，默认为 `600`)：每个沙箱的空闲超时时间——沙箱在主机上闲置超过此时长（无 API 调用、无运行中的进程）后将被驱逐。这与主机空闲超时不同。传入 `None` 可禁用此功能。

forward_hf_token (`bool`，*可选*，默认为 `False`)：如果为 True，则在沙箱中注入您的 HF token 作为 `HF_TOKEN`（需主动选择）。与专用沙箱的 `secrets` 不同，池化沙箱的环境变量在创建时即交付给主机服务器（不会存储在主机作业中），因此不会出现在任何作业的元数据中。

创建一个沙箱，如有需要则配置一台主机。

在启动新主机之前，会优先复用具有空闲容量的主机（本池中的主机，或通过作业标签 / 本地缓存找到的预热主机），因此对预热主机调用 `create()` 的成本约为一次往返。可重复调用该方法以进行扇出；使用 `warm_up`（或 `warm`）可预先配置主机，避免首次调用时出现冷启动。如果主机容量被占满（例如被其他进程填满）或缓存的主机已消失，沙箱将被重新部署到另一台主机（或一台新主机）上。

#### warm[[huggingface_hub.SandboxPool.warm]]

```python
warm(num_hosts: int = 1)
```

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

确保 `num_hosts` 个空主机正在运行，并保持其运行状态。返回池的主机作业 ID。

用于预先“创建”一个池：主机上带有池的标签和配置（位于其环境变量中），因此后续的 `SandboxPool.connect(pool_id)`（即使来自另一台机器）也能找到它们并生成沙箱，而无需冷启动。在主机被终止或处于空闲状态之前，会持续计费。

在启动之前，会先采用该池中已在运行的主机（通过作业标签查找），因此在 `connect()` 之后调用 `warm()` —— 或重复调用 `warm()` —— 会将主机数量补足至 `num_hosts`，而不是重复创建正在运行的主机并超出 `max_hosts` 的限制。

## 数据结构

### SandboxCommandResult[[huggingface_hub.SandboxCommandResult]]

#### huggingface_hub.SandboxCommandResult[[huggingface_hub.SandboxCommandResult]]

```python
huggingface_hub.SandboxCommandResult(exit_code: int | None, stdout: str, stderr: str, signal: int | None = None, timed_out: bool = False, duration_ms: int = 0)
```

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

在沙箱中通过 [Sandbox.run()](/docs/huggingface_hub/v2.4.0/zh/package_reference/sandbox#huggingface_hub.Sandbox.run) 执行命令的结果。

### SandboxProcess[[huggingface_hub.SandboxProcess]]

#### huggingface_hub.SandboxProcess[[huggingface_hub.SandboxProcess]]

```python
huggingface_hub.SandboxProcess(id: str | None, pid: int, cmd: typing.Union[str, typing.List[str]], _sandbox: Sandbox, tag: str | None = None, started_at_ms: int | None = None, running: bool = True, exit_code: int | None = None)
```

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

在沙箱中通过 [Sandbox.run()](/docs/huggingface_hub/v2.4.0/zh/package_reference/sandbox#huggingface_hub.Sandbox.run)`(..., background=True)` 启动的后台进程。

使用 [Sandbox.processes()](/docs/huggingface_hub/v2.4.0/zh/package_reference/sandbox#huggingface_hub.Sandbox.processes) 列出沙箱中的进程，并使用 [SandboxProcess.kill()](/docs/huggingface_hub/v2.4.0/zh/package_reference/sandbox#huggingface_hub.SandboxProcess.kill) 终止其中一个进程。最近完成的进程会保留在列表中（服务器会保留有限数量的此类进程），因此 `running` 和 `exit_code` 可用于判断进程是否仍在运行或已经退出（以列出时的状态为准）。

#### kill[[huggingface_hub.SandboxProcess.kill]]

```python
kill()
```

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

终止后台进程。幂等。

返回此调用是否导致其停止：`False` 表示它已经退出或被终止，这不算错误。

请注意，通过 `setsid()` 分离的后代进程会离开被通知的进程组，并在此调用之后继续存活。请删除沙箱，以确保其启动的所有内容均已终止。

### FileEntry[[huggingface_hub._sandbox.FileEntry]]

#### huggingface_hub._sandbox.FileEntry[[huggingface_hub._sandbox.FileEntry]]

```python
huggingface_hub._sandbox.FileEntry(name: str, path: str, type: typing.Literal['file', 'dir', 'symlink'], size: int, mtime_ms: int | None = None, mode: str = '')
```

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

沙箱内的文件或目录。

## 错误

### SandboxError[[huggingface_hub.errors.SandboxError]]

#### huggingface_hub.errors.SandboxError[[huggingface_hub.errors.SandboxError]]

```python
huggingface_hub.errors.SandboxError(message: str, status_code: int | None = None)
```

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

**参数：**

status_code : 如果错误源自 API 响应（例如，文件缺失时返回 `404`），则为沙箱内服务器返回的 HTTP 状态码。否则为 `None`。

沙箱操作的基础异常（参见 `huggingface_hub.Sandbox`）。

### SandboxCommandError[[huggingface_hub.errors.SandboxCommandError]]

#### huggingface_hub.errors.SandboxCommandError[[huggingface_hub.errors.SandboxCommandError]]

```python
huggingface_hub.errors.SandboxCommandError(cmd, result)
```

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

**参数：**

cmd : 失败的命令。

result : 完整的 `SandboxCommandResult`（exit_code、stdout、stderr 等）。

当在沙箱中运行的命令以非零代码退出时引发。