沙盒

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

查看沙箱指南以了解如何使用它们。

沙盒

类 huggingface_hub.Sandbox

( id: strserver: _SandboxServerlocal_id: str | Noneowns_sandbox: boolowns_server: boolsandbox_token: str | None = None )

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

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

使用 Sandbox.create() 创建一个专用的沙箱（每个沙箱对应一个任务），或者从 SandboxPool 中获取多个低成本的共享沙箱。

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

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

关闭

< source >

( )

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

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

连接

< source >

( sandbox_id: strnamespace: str | None = Nonetoken: str | None = None )

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

创建

< source >

( image: str = 'python:3.12'flavor: str = 'cpu-basic'idle_timeout: int | float | str | None = 600env: dict[str, typing.Any] | None = Nonesecrets: dict[str, typing.Any] | None = Nonevolumes: typing.Optional[typing.List[huggingface_hub._space_api.Volume]] = Nonenamespace: str | None = Noneforward_hf_token: bool = Falselabels: dict[str, str] | None = Nonestart_timeout: float = 120.0token: str | None = None )

参数

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。
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 token 覆盖。

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

每个沙箱都是一个完全隔离的虚拟机，因此它是 GPU 工作负载或不可信代码的正确选择。若要并行分发大量低成本的 CPU 沙箱，请使用 SandboxPool。

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

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

进程

< source >

( )

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

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

proxy_url_for

< source >

( port: int | strpath: str = '/'scheme: str = 'https://' ) → str

参数

port (int 或 str) — 内部服务器监听的端口（池：unix 套接字的 <port>）。
path (str，可选，默认为 "/") — 内部服务器上要指向的路径，例如 "/ws"。
scheme (str, 可选，默认为 "https --//")：用于构建链接的 URL 协议。默认为 "https://"；对于 WebSocket 客户端，请传入 "wss://"（代理与协议无关，因此只有客户端侧的协议会发生变化）。

返回值

str

类似 https://<job_id>--49983.hf.jobs/v1/.../proxy/8000/ws 的 URL（或使用 scheme="wss://" 的 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 端口。（你也可以通过作业代理直接暴露该端口，而无需经过此处。）

示例：

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

运行

< source >

( cmd: typing.Union[str, typing.List[str]]shell: bool | None = Noneenv: dict[str, typing.Any] | None = Nonecwd: str | None = Nonetimeout: float | None = Nonestdin: str | None = Noneon_stdout: typing.Optional[typing.Callable[[str], NoneType]] = Noneon_stderr: typing.Optional[typing.Callable[[str], NoneType]] = Nonecheck: bool = Truecapture_output: bool = Truebackground: bool = False )

参数

cmd (str 或 List[str]) — Shell 命令字符串（通过 /bin/sh -c 运行）或 argv 列表（直接执行）。
shell (bool, 可选) — 强制指定执行模式，而不是根据 cmd 的类型进行推断。 True 通过 /bin/sh -c 运行，并要求 cmd 为字符串；False 直接 exec cmd，并要求其为 argv 列表。None（默认值）根据类型进行推断。请显式设置该参数以避免由类型引发的陷阱（例如 ["echo hi"] 被作为名为 "echo hi" 的单个程序执行）。
env (dict[str, Any]，可选) — 此命令的额外环境变量。
cwd (str, 可选) — 工作目录。
timeout (float, 可选) — 在此秒数后终止命令（整个进程组）。
stdin (str, 可选) — 要写入命令 stdin 的数据。
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，而不是等待其完成并返回一个 SandboxCommandResult。

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

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

返回：一个 SandboxCommandResult（包含 exit_code、stdout、stderr、duration_ms），或者当 background=True 时返回一个 SandboxProcess。

SandboxPool

类 huggingface_hub.SandboxPool

< source >

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

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

池化沙箱适用于同一信任边界内的工作负载。 池化沙箱是共享虚拟机内的一个 uid 加上一组 Landlock 规则集——而非独立的虚拟机——并且主机上的每个沙箱都共享该主机的身份验证令牌及其特权控制平面。使用池化沙箱可以低成本地并行运行您自己的代码。对于相互不信任的工作负载，请使用 Sandbox.create()，它将为每个工作负载提供独立的虚拟机。具体的局限性列在沙箱概念指南的“已知限制”部分。

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

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

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

>>> 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 的新池会附加到

是之前运行留下的）：

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

关闭

< source >

( )

释放池。幂等。

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

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

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

连接

< source >

( pool_id: strnamespace: str | None = Noneadopt_hosts: str = 'own'token: str | None = None )

参数

pool_id (str) — 池首次创建时返回的 id。
namespace (str，可选) — 用于搜索池主机的命名空间（默认为您自己的命名空间）。
adopt_hosts (str，可选，默认为 "own") — 可以附加到哪些主机。参见 SandboxPool。若要重新附加到由命名空间中其他成员启动的主机组成的池，则需要 "namespace"。
token (str, 可选) — HF token 覆盖。

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

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

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

创建

< source >

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

参数

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）可预先配置主机，避免首次调用时出现冷启动。如果主机容量被占满（例如被其他进程填满）或缓存的主机已消失，沙箱将被重新部署到另一台主机（或一台新主机）上。

预热

< source >

( num_hosts: int = 1 )

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

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

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

数据结构

SandboxCommandResult

类 huggingface_hub.SandboxCommandResult

< source >

( exit_code: int | Nonestdout: strstderr: strsignal: int | None = Nonetimed_out: bool = Falseduration_ms: int = 0 )

在沙箱中通过 Sandbox.run() 执行命令的结果。

SandboxProcess

类 huggingface_hub.SandboxProcess

< source >

( id: str | Nonepid: intcmd: typing.Union[str, typing.List[str]]_sandbox: Sandboxtag: str | None = Nonestarted_at_ms: int | None = Nonerunning: bool = Trueexit_code: int | None = None )

在沙箱中通过 Sandbox.run()(..., background=True) 启动的后台进程。

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

kill

< source >

( )

终止后台进程。幂等。

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

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

FileEntry

class huggingface_hub._sandbox.FileEntry

< source >

( name: strpath: strtype: typing.Literal['file', 'dir', 'symlink']size: intmtime_ms: int | None = Nonemode: str = '' )

沙箱内的文件或目录。

错误

SandboxError

类 huggingface_hub.errors.SandboxError

< source >

( message: strstatus_code: int | None = None )

参数

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

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

SandboxCommandError

类 huggingface_hub.errors.SandboxCommandError

< source >

( cmdresult )

参数

cmd — 失败的命令。
result — 完整的 SandboxCommandResult（exit_code、stdout、stderr 等）。

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

Update on GitHub

Hub Python Library

沙盒

沙盒

类 huggingface_hub.Sandbox

关闭

连接

创建

进程

proxy_url_for

运行

SandboxPool

类 huggingface_hub.SandboxPool

关闭

连接

创建

预热

数据结构

SandboxCommandResult

类 huggingface_hub.SandboxCommandResult

SandboxProcess

类 huggingface_hub.SandboxProcess

kill

FileEntry

class huggingface_hub._sandbox.FileEntry

错误

SandboxError

类 huggingface_hub.errors.SandboxError

SandboxCommandError

类 huggingface_hub.errors.SandboxCommandError