# Các môi trường cách ly

> [!NOTE]
> API Sandbox mang tính thử nghiệm. API và hành vi của nó có thể thay đổi mà không có thông báo trước. Các sandbox dùng chung được thiết kế cho các tác vụ nằm trong cùng một ranh giới tin cậy; hãy sử dụng các sandbox riêng biệt cho các tác vụ không tin tưởng lẫn nhau.

Xem [hướng dẫn về Sandboxes](../guides/sandbox) để tìm hiểu cách sử dụng chúng.

## 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)
```

[Nguồn](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/_sandbox.py#L783)

Một máy cloud độc lập chạy trên Hugging Face Jobs.

> [!NOTE]
> API Sandbox mang tính thử nghiệm. API và hành vi của nó có thể thay đổi mà không cần thông báo trước.

Tạo một sandbox riêng bằng [Sandbox.create()](/docs/huggingface_hub/v2.4.0/vi/package_reference/sandbox#huggingface_hub.Sandbox.create) (một job cho mỗi sandbox), hoặc lấy nhiều sandbox dùng chung giá rẻ từ [SandboxPool](/docs/huggingface_hub/v2.4.0/vi/package_reference/sandbox#huggingface_hub.SandboxPool).

Kết nối lại với một sandbox đang chạy từ bất kỳ đâu bằng [Sandbox.connect()](/docs/huggingface_hub/v2.4.0/vi/package_reference/sandbox#huggingface_hub.Sandbox.connect). Sử dụng như một context manager để kết thúc nó khi thoát:

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

#### đóng[[huggingface_hub.Sandbox.close]]

```python
close()
```

[Nguồn](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/_sandbox.py#L1028)

Phóng thích client HTTP cục bộ mà không kết thúc sandbox. Idempotent.

Không thực hiện thao tác nào với các sandbox pool (client thuộc về host của pool).

#### kết nối[[huggingface_hub.Sandbox.connect]]

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

[Nguồn](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/_sandbox.py#L952)

Kết nối lại với một sandbox đang chạy từ bất kỳ đâu, chỉ cần sử dụng id của nó.

#### tạo[[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)
```

[Nguồn](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/_sandbox.py#L835)

**Tham số:**

image (`str`, *tùy chọn*, mặc định là `"python --3.12"`): Bất kỳ hình ảnh Docker nào có `/bin/sh` (Docker Hub hoặc `hf.co/spaces/...`).

flavor (`str`, *tùy chọn*, mặc định là `"cpu-basic"`) : Loại phần cứng, ví dụ `"cpu-basic"`, `"a10g-small"`. Xem `hf jobs hardware`.

idle_timeout (`int` hoặc `float` hoặc `str`, *tuỳ chọn*, mặc định là `600`) : Tự động tắt sau khoảng thời gian không hoạt động này (không có cuộc gọi API, không có tiến trình đang chạy). Mặc định là 10 phút; truyền `None` để tắt tính năng này. Lưu ý rằng một lệnh *foreground* hiện không được tính là hoạt động, do đó một lệnh `run()` duy nhất mất nhiều thời gian hơn mức này mà không có lưu lượng API khác có thể khiến sandbox bị tắt ngay khi đang chạy — hãy tăng thời gian chờ (hoặc truyền `None`) cho các lệnh đơn lẻ kéo dài.

env (`dict[str, Any]`, *tùy chọn*) : Các biến môi trường có sẵn trong sandbox.

secrets (`dict[str, Any]`, *tùy chọn*) : Các biến môi trường bí mật (được mã hóa phía máy chủ).

volumes (`List[Volume]`, *tùy chọn*) : các kho/bucket HF để gắn, xem [Volume](/docs/huggingface_hub/v2.4.0/vi/package_reference/jobs#huggingface_hub.Volume).

namespace (`str`, *tùy chọn*) : Không gian tên của người dùng hoặc tổ chức để chạy (mặc định là người dùng hiện tại).

forward_hf_token (`bool`, *tùy chọn*, mặc định là `False`) : Nếu là True, token HF của bạn sẽ được chèn dưới dạng `HF_TOKEN` (chọn tham gia).

labels (`dict[str, str]`, *tùy chọn*) : Nhãn để gắn cho HF Job bên dưới.

start_timeout (`float`, *tuỳ chọn*, mặc định là `120.0`) : Số giây tối đa để chờ sandbox sẵn sàng.

token (`str`, *tùy chọn*) : ghi đè token HF.

Tạo một sandbox riêng (một HF Job) và chặn cho đến khi nó sẵn sàng (~7s trên cpu-basic).

Mỗi sandbox là một VM cách ly hoàn toàn, vì vậy đây là lựa chọn phù hợp cho các tác vụ GPU hoặc mã không đáng tin cậy. Để triển khai nhiều sandbox CPU giá rẻ hơn, hãy sử dụng [SandboxPool](/docs/huggingface_hub/v2.4.0/vi/package_reference/sandbox#huggingface_hub.SandboxPool).

Công việc chạy với thời gian tồn tại tối đa cố định là 24 giờ; `idle_timeout` mới là yếu tố quyết định — một sandbox ở trạng thái nhàn rỗi sẽ tự động tắt trước thời điểm đó rất lâu.

Hình ảnh chỉ cần `/bin/sh`. Máy chủ sandbox sẽ được tải xuống khi khởi động bằng `wget`/`curl` nếu có sẵn, nếu không sẽ được đọc từ một bucket máy chủ luôn được gắn (điều này làm tăng thời gian khởi động lạnh khoảng 2-3 giây, do đó việc cung cấp sẵn `wget`/`curl` giúp duy trì tốc độ nhanh).

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

```python
processes()
```

[Nguồn](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/_sandbox.py#L1202)

Liệt kê các tiến trình nền của sandbox này.

Trả về các tiến trình được khởi chạy bằng [Sandbox.run()](/docs/huggingface_hub/v2.4.0/vi/package_reference/sandbox#huggingface_hub.Sandbox.run)`(..., background=True)`; dừng một tiến trình bằng [SandboxProcess.kill()](/docs/huggingface_hub/v2.4.0/vi/package_reference/sandbox#huggingface_hub.SandboxProcess.kill). Các tiến trình vừa hoàn thành vẫn được liệt kê (với `running=False` và `exit_code` của chúng); máy chủ chỉ giữ một số lượng có giới hạn các tiến trình này, nên một sandbox đã chạy hàng nghìn lệnh ngắn sẽ không liệt kê tất cả chúng.

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

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

[Nguồn](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/_sandbox.py#L1238)

**Tham số:**

port (`int` hoặc `str`) : Cổng (pool: `<port>` của unix socket) mà máy chủ bên trong lắng nghe.

path (`str`, *tùy chọn*, mặc định là `"/"`) : Đường dẫn trên máy chủ bên trong cần trỏ đến, ví dụ `"/ws"`.

scheme (`str`, *tùy chọn*, mặc định là `"https --//"`): URL scheme để xây dựng liên kết. Mặc định là `"https://"`; truyền `"wss://"` cho một client WebSocket (proxy không phụ thuộc vào giao thức, nên chỉ scheme phía client thay đổi).

**Trả về:** `str`

một URL như `https://<job_id>--49983.hf.jobs/v1/.../proxy/8000/ws` (hoặc `wss://...` với `scheme="wss://"`).

URL công khai được proxy đến một máy chủ chạy *bên trong* sandbox này.

Các yêu cầu đến URL được trả về sẽ được chuyển tiếp bởi máy chủ sandbox trong job đến máy chủ mà bạn đã khởi chạy trong sandbox trên `port`, bao gồm cả nâng cấp WebSocket (`ws(s)://`) và các phản hồi dạng luồng. Kết hợp với `proxy_headers` để xác thực.

Cách sandbox phải lắng nghe trên `port`:

- **Pool / sandbox dùng chung**: không thể bind cổng TCP (Landlock), do đó hãy bind một **unix socket** tại `$SBX_PROXY_DIR/<port>.sock` (biến môi trường `SBX_PROXY_DIR` được đặt trong mọi sandbox). Ví dụ: `uvicorn app:app --uds $SBX_PROXY_DIR/8000.sock`.
- **Không gian riêng biệt**: gắn một cổng TCP thông thường vào `127.0.0.1:<port>`. (Bạn cũng có thể phơi bày trực tiếp cổng này qua proxy của job mà không cần đi qua đây.)

Ví dụ:
```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")
```

#### chạy[[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)
```

[Nguồn](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/_sandbox.py#L1075)

**Tham số:**

cmd (`str` hoặc `List[str]`) : Chuỗi lệnh shell (chạy với `/bin/sh -c`) hoặc danh sách argv (được thực thi trực tiếp).

shell (`bool`, *tùy chọn*) : Buộc chế độ thực thi thay vì suy luận từ kiểu của `cmd`. `True` chạy thông qua `/bin/sh -c` và yêu cầu `cmd` phải là một chuỗi; `False` thực thi `cmd` trực tiếp và yêu cầu nó phải là một danh sách argv. `None` (mặc định) suy luận từ kiểu. Đặt giá trị này một cách rõ ràng để tránh bẫy do kiểu dữ liệu gây ra (ví dụ: `["echo hi"]` bị thực thi như một chương trình duy nhất có tên là `"echo hi"`).

env (`dict[str, Any]`, *tùy chọn*) : Các biến môi trường bổ sung cho lệnh này.

cwd (`str`, *tùy chọn*) : Thư mục làm việc.

timeout (`float`, *optional*) : Kết thúc lệnh (toàn bộ nhóm tiến trình) sau số giây này.

stdin (`str`, *tùy chọn*) : Dữ liệu để ghi vào stdin của lệnh.

on_stdout (`Callable[[str], None]`, *tùy chọn*) : Callback được gọi với các khối stdout khi chúng đến.

on_stderr (`Callable[[str], None]`, *tùy chọn*) : Callback được gọi với các khối stderr khi chúng đến.

check (`bool`, *tùy chọn*, mặc định là `True`) : Nếu là True, sẽ gây ra `SandboxCommandError` khi mã thoát khác không.

capture_output (`bool`, *tuỳ chọn*, mặc định là `True`) : Nếu là True, sẽ tích lũy stdout/stderr vào kết quả được trả về. Truyền `False` khi bạn chỉ muốn dùng `on_stdout`/`on_stderr`: đầu ra sau đó sẽ được chuyển cho các callback và bị bỏ đi, do đó một lệnh tạo ra hàng gigabyte dữ liệu không cần phải vừa trong bộ nhớ. `result.stdout`/`result.stderr` sẽ trống trong trường hợp đó.

background (`bool`, *tuỳ chọn*, mặc định là `False`) : Nếu là True, bắt đầu lệnh ở chế độ tách rời và trả về một [SandboxProcess](/docs/huggingface_hub/v2.4.0/vi/package_reference/sandbox#huggingface_hub.SandboxProcess) ngay lập tức thay vì chờ đợi và trả về một [SandboxCommandResult](/docs/huggingface_hub/v2.4.0/vi/package_reference/sandbox#huggingface_hub.SandboxCommandResult).

Chạy một lệnh trong sandbox và chờ nó, đồng thời phát trực tiếp đầu ra.

Với `background=True`, lệnh được khởi chạy ở chế độ tách rời và `run` trả về một [SandboxProcess](/docs/huggingface_hub/v2.4.0/vi/package_reference/sandbox#huggingface_hub.SandboxProcess) ngay lập tức, không chờ nó hoàn tất — rất tiện cho các máy chủ và các tiến trình chạy dài. Bạn có thể liệt kê chúng sau đó bằng [Sandbox.processes()](/docs/huggingface_hub/v2.4.0/vi/package_reference/sandbox#huggingface_hub.Sandbox.processes) và dừng một tiến trình bằng [SandboxProcess.kill()](/docs/huggingface_hub/v2.4.0/vi/package_reference/sandbox#huggingface_hub.SandboxProcess.kill). Các tùy chọn chỉ dành cho streaming/chờ (`timeout`, `stdin`, `on_stdout`, `on_stderr`, `check`) không áp dụng trong chế độ đó.

Trả về: một [SandboxCommandResult](/docs/huggingface_hub/v2.4.0/vi/package_reference/sandbox#huggingface_hub.SandboxCommandResult) (với `exit_code`, `stdout`, `stderr`, `duration_ms`), hoặc một [SandboxProcess](/docs/huggingface_hub/v2.4.0/vi/package_reference/sandbox#huggingface_hub.SandboxProcess) khi `background=True`.

## 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)
```

[Nguồn](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/_sandbox.py#L1313)

Một đội gồm các tác vụ "host" dùng chung, mỗi tác vụ chứa nhiều sandbox được cách ly bằng landlock.

> [!WARNING]
> API Sandbox mang tính thử nghiệm. API và hành vi của nó có thể thay đổi mà không cần thông báo trước.
>
> **Các sandbox dạng pooled dành cho các tác vụ nằm trong cùng một ranh giới tin cậy.** Một sandbox pooled là một uid cùng một bộ quy tắc Landlock bên trong một VM dùng chung — không phải một VM riêng — và mọi sandbox trên một host đều dùng chung token xác thực của host đó cùng mặt phẳng điều khiển có đặc quyền. Hãy dùng một pool để triển khai *mã của chính bạn* một cách tiết kiệm. Đối với các tác vụ không tin tưởng lẫn nhau, hãy dùng [Sandbox.create()](/docs/huggingface_hub/v2.4.0/vi/package_reference/sandbox#huggingface_hub.Sandbox.create), trong đó mỗi tác vụ sẽ có một VM riêng. Các khoảng trống cụ thể được liệt kê dưới mục "Known limitations" trong hướng dẫn khái niệm về sandbox.

Một host là một HF Job được tính phí (một VM); nó chạy sandbox server và multiplex tối đa `sandboxes_per_host` sandbox nhẹ, được cách ly khỏi nhau bằng uid + Landlock LSM. Điều này giúp các fan-out lớn trở nên rẻ (chi phí VM được chia sẻ giữa tất cả sandbox của nó) và nhanh (việc tạo một sandbox chỉ mất ~một lượt proxy round-trip khi host đã warm). Phù hợp nhất cho nhiều sandbox CPU song song như RL rollouts; đối với GPU hoặc cách ly ở cấp VM mạnh giữa các workload không tin tưởng lẫn nhau, hãy dùng [Sandbox.create()](/docs/huggingface_hub/v2.4.0/vi/package_reference/sandbox#huggingface_hub.Sandbox.create) thay thế.

Bộ khởi tạo cấp phát trước `warm_up` máy chủ (mặc định là 1) và chặn cho đến khi chúng sẵn sàng; các máy chủ tiếp theo sẽ được cấp phát theo nhu cầu khi có yêu cầu sandbox, và tất cả

được gỡ bỏ khi `close()` (hoặc khi nhàn rỗi, thông qua `idle_timeout`). Người dùng không bao giờ quản lý các tác vụ:

```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()` tạo **một** sandbox mỗi lần: nó tái sử dụng một host vẫn còn dung lượng trống trước khi khởi động một host mới, nhờ đó bạn mở rộng theo nhu cầu khi công việc đến. Để tránh khởi động lạnh trong vài lần gọi đầu tiên, hãy cung cấp trước các host bằng `warm_up` (hoặc `warm`). Các host ấm được phát hiện thông qua nhãn công việc, nên việc tái sử dụng cũng hoạt động **giữa các tiến trình** (một pool mới với cùng `image`/`flavor`/`name` sẽ gắn vào

chứa một lần chạy trước đó để lại):

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

#### đóng[[huggingface_hub.SandboxPool.close]]

```python
close()
```

[Nguồn](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/_sandbox.py#L1729)

Giải phóng pool. Idempotent.

Đối với pool do chúng ta tạo, thao tác này sẽ kết thúc tất cả các job trên host (và do đó kết thúc tất cả các sandbox của chúng). Đối với handle đã được `connect()`, nó chỉ giải phóng các client HTTP cục bộ: các host dùng chung có thể đang phục vụ các client khác, nên — giống như [Sandbox.connect()](/docs/huggingface_hub/v2.4.0/vi/package_reference/sandbox#huggingface_hub.Sandbox.connect) — việc thoát khỏi khối `with` không được phép hủy bỏ chúng. Hãy kết thúc các host của pool đã kết nối một cách tường minh bằng `hf sandbox pool delete <id>`.

Chỉ các host *mà chúng ta khởi động* mới bị hủy. Một host được phát hiện thông qua nhãn có thể đang phục vụ các sandbox của một tiến trình khác, do đó nó được giải phóng thay vì bị kết thúc.

Ném `SandboxError` nếu một tác vụ trên host không thể bị hủy, kèm theo tên của các tác vụ vẫn đang chạy — chúng tiếp tục bị tính phí và các mục cache của chúng được giữ lại để vẫn có thể truy xuất được. Khi `close()` được gọi thông qua `__exit__` trong khi một ngoại lệ đã đang diễn ra, lỗi sẽ được ghi log thay vì được ném ra, để không che lấp lỗi gốc.

#### kết nối[[huggingface_hub.SandboxPool.connect]]

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

[Nguồn](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/_sandbox.py#L1494)

**Tham số:**

pool_id (`str`) : id được trả về khi pool được tạo lần đầu.

namespace (`str`, *tùy chọn*) : Namespace để tìm kiếm các host của pool (mặc định là namespace của bạn).

adopt_hosts (`str`, *tùy chọn*, mặc định là `"own"`) : Các host nào có thể được gắn vào. Xem [SandboxPool](/docs/huggingface_hub/v2.4.0/vi/package_reference/sandbox#huggingface_hub.SandboxPool). Việc gắn lại vào một pool mà các host của nó đã được một thành viên khác trong namespace khởi tạo cần `"namespace"`.

token (`str`, *tùy chọn*) : ghi đè token HF.

Gắn lại vào một pool đang chạy theo id, từ bất kỳ máy nào — không cần trạng thái cục bộ.

Tìm một host đang chạy được gắn nhãn `pool_id` và xây dựng lại cấu hình của pool (image/flavor/density/host-idle) từ spec và các biến môi trường của job host đó, trả về một [SandboxPool](/docs/huggingface_hub/v2.4.0/vi/package_reference/sandbox#huggingface_hub.SandboxPool) sẵn sàng để `create()` thêm các sandbox — đóng gói lên các host đang chạy, hoặc khởi động một bản sao (cùng cấu hình) khi chúng đã đầy.

Ném `SandboxError` nếu không tìm thấy host nào đang chạy (một pool sẽ ngừng tồn tại khi tất cả các host của nó biến mất — do hết thời gian chờ nhàn rỗi hoặc bị kết thúc).

#### tạo[[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)
```

[Nguồn](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/_sandbox.py#L1591)

**Tham số:**

env (`dict[str, Any]`, *tùy chọn*) : Các biến môi trường cho sandbox này (mỗi sandbox có bộ biến riêng).

idle_timeout (`int` hoặc `float` hoặc `str`, *tuỳ chọn*, mặc định là `600`) : Thời gian chờ nhàn rỗi cho từng sandbox — một sandbox sẽ bị loại khỏi host sau khoảng thời gian không hoạt động này (không có cuộc gọi API, không có tiến trình đang chạy). Khác với thời gian chờ nhàn rỗi của host. Truyền `None` để tắt.

forward_hf_token (`bool`, *tuỳ chọn*, mặc định là `False`) : Nếu là True, sẽ tiêm token HF của bạn dưới dạng `HF_TOKEN` trong sandbox (chọn tham gia). Khác với `secrets` của một sandbox chuyên dụng, biến môi trường của sandbox dạng pooled được chuyển đến máy chủ host khi tạo (không bao giờ được lưu trong job của host), do đó nó không xuất hiện trong metadata của bất kỳ job nào.

Tạo một sandbox, cấp phát một host nếu cần.

Tái sử dụng một host có dung lượng trống (của pool này, hoặc một host ấm được tìm thấy qua nhãn job / bộ nhớ đệm cục bộ) trước khi khởi động một host mới, do đó một lệnh `create()` trên một host ấm chỉ tốn khoảng một lượt đi-về. Gọi lệnh này nhiều lần để phân tán; sử dụng `warm_up` (hoặc `warm`) để cung cấp trước các host và tránh khởi động lạnh ở các lần gọi đầu tiên. Nếu một host bị đầy dưới chân chúng ta (một tiến trình khác đã lấp đầy nó) hoặc một host trong bộ nhớ đệm đã biến mất, sandbox sẽ được đặt lại trên một host khác (hoặc một host mới).

#### ấm[[huggingface_hub.SandboxPool.warm]]

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

[Nguồn](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/_sandbox.py#L1564)

Đảm bảo `num_hosts` host trống đang chạy và giữ cho chúng tiếp tục chạy. Trả về các id job của host trong pool.

Được dùng để "tạo" sẵn một pool: các host mang nhãn và cấu hình của pool (trong các biến môi trường của chúng), do đó một lệnh `SandboxPool.connect(pool_id)` sau đó (ngay cả từ một máy khác) sẽ tìm thấy chúng và khởi tạo các sandbox mà không cần khởi động lạnh. Các host tiếp tục bị tính phí cho đến khi bị kết thúc hoặc ở trạng thái nhàn rỗi.

Nhận các host đã đang chạy cho pool này (tìm thấy qua nhãn của job) trước khi khởi động, do đó một `warm()` sau `connect()` — hoặc một `warm()` lặp lại — sẽ bổ sung lên đến `num_hosts` thay vì nhân bản các host đang hoạt động và vượt quá `max_hosts`.

## Cấu trúc dữ liệu

### 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)
```

[Nguồn](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/_sandbox.py#L191)

Kết quả của một lệnh được thực thi trong sandbox bằng [Sandbox.run()](/docs/huggingface_hub/v2.4.0/vi/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)
```

[Nguồn](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/_sandbox.py#L211)

Một tiến trình nền được khởi động trong một sandbox bằng [Sandbox.run()](/docs/huggingface_hub/v2.4.0/vi/package_reference/sandbox#huggingface_hub.Sandbox.run)`(..., background=True)`.

Danh sách các tiến trình của một sandbox bằng [Sandbox.processes()](/docs/huggingface_hub/v2.4.0/vi/package_reference/sandbox#huggingface_hub.Sandbox.processes) và dừng một tiến trình bằng [SandboxProcess.kill()](/docs/huggingface_hub/v2.4.0/vi/package_reference/sandbox#huggingface_hub.SandboxProcess.kill). Các tiến trình vừa hoàn thành vẫn được giữ trong danh sách (máy chủ giữ một số lượng có giới hạn), do đó `running` và `exit_code` cho biết một tiến trình vẫn đang chạy hay đã thoát (tính đến thời điểm nó được liệt kê).

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

```python
kill()
```

[Nguồn](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/_sandbox.py#L235)

Kết thúc tiến trình nền. Idempotent.

Trả về việc cuộc gọi này có phải là nguyên nhân khiến nó dừng lại hay không: `False` có nghĩa là nó đã thoát hoặc bị kết thúc trước đó, điều này không phải là lỗi.

Lưu ý rằng một tiến trình con tách ra bằng `setsid()` sẽ rời khỏi nhóm tiến trình được gửi tín hiệu và tồn tại lâu hơn lệnh gọi này. Hãy xóa sandbox để chắc chắn rằng mọi thứ nó khởi động đã bị xóa sạch.

### 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 = '')
```

[Nguồn](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/_sandbox.py#L256)

Một tệp hoặc thư mục bên trong sandbox.

## Lỗi

### 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)
```

[Nguồn](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/errors.py#L598)

**Tham số:**

status_code : Trạng thái HTTP do máy chủ trong sandbox trả về, nếu lỗi bắt nguồn từ phản hồi API (ví dụ `404` cho tệp bị thiếu). `None` trong các trường hợp khác.

Ngoại lệ cơ bản cho các thao tác sandbox (xem `huggingface_hub.Sandbox`).

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

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

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

[Nguồn](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/errors.py#L611)

**Tham số:**

cmd : Lệnh đã thất bại.

result : `SandboxCommandResult` đầy đủ (exit_code, stdout, stderr, ...).

Được kích hoạt khi một lệnh được chạy trong sandbox thoát với mã khác không.