# صناديق الرمل

> [!NOTE]
> واجهة برمجة التطبيقات الخاصة ببيئة العزل تجريبية. قد تتغير واجهتها وسلوكها دون إشعار مسبق. تُصمَّم بيئات العزل المشتركة للأحمال العاملة ضمن نطاق الثقة نفسه؛ استخدم بيئات عزل مخصصة للأحمال التي لا تثق ببعضها البعض.

اطّلع على [دليل بيئات العزل](../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 تجريبية. قد تتغير واجهتها وسلوكها دون إشعار مسبق.

أنشئ بيئة مخصصة واحدة باستخدام [Sandbox.create()](/docs/huggingface_hub/v2.4.0/ar/package_reference/sandbox#huggingface_hub.Sandbox.create) (مهمة واحدة لكل بيئة)، أو احصل على العديد من البيئات المشتركة منخفضة التكلفة من [SandboxPool](/docs/huggingface_hub/v2.4.0/ar/package_reference/sandbox#huggingface_hub.SandboxPool).

أعد الاتصال ببيئة اختبار قيد التشغيل من أي مكان باستخدام [Sandbox.connect()](/docs/huggingface_hub/v2.4.0/ar/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)

إعادة الاتصال ببيئة اختبار قيد التشغيل من أي مكان، باستخدام معرّفها فقط.

#### إنشاء[[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"`): أي صورة Docker تحتوي على `/bin/sh` (Docker Hub أو `hf.co/spaces/...`).

flavor (`str`، *اختياري*، القيمة الافتراضية `"cpu-basic"`) : نوع العتاد، مثل `"cpu-basic"`، `"a10g-small"`. راجع `hf jobs hardware`.

idle_timeout (`int` أو `float` أو `str`، *اختياري*، القيمة الافتراضية `600`) : إيقاف تلقائي بعد هذه المدة من عدم النشاط (لا توجد استدعاءات لواجهات برمجة التطبيقات، ولا توجد عمليات قيد التنفيذ). القيمة الافتراضية هي 10 دقائق؛ مرّر `None` لتعطيلها. لاحظ أن أمر *foreground* لا يُحتسب حاليًا كنشاط، لذا فإن استدعاء `run()` واحد يستغرق وقتًا أطول من هذه المدة دون أي حركة أخرى لواجهات برمجة التطبيقات قد يؤدي إلى إيقاف بيئة العزل الخاصة به — ارفع مهلة الإيقاف (أو مرّر `None`) للأوامر الفردية الطويلة.

env (`dict[str, Any]`، *اختياري*) : متغيرات البيئة المتاحة في بيئة العزل.

secrets (`dict[str, Any]`، *اختياري*) : متغيرات البيئة السرية (تُشفَّر على جانب الخادم).

volumes (`List[Volume]`، *اختياري*) : مستودعات/دلاء HF التي سيتم تركيبها، راجع [Volume](/docs/huggingface_hub/v2.4.0/ar/package_reference/jobs#huggingface_hub.Volume).

namespace (`str`، *اختياري*) : مساحة الاسم للمستخدم أو المنظمة التي سيتم التشغيل تحتها (الافتراضي هو المستخدم الحالي).

forward_hf_token (`bool`، *اختياري*، القيمة الافتراضية `False`) : إذا كانت القيمة True، يتم حقن رمز HF الخاص بك على أنه `HF_TOKEN` (بانتساب اختياري).

labels (`dict[str, str]`، *اختياري*) : التسميات التي سيتم إرفاقها بوظيفة HF الأساسية.

start_timeout (`float`، *اختياري*، القيمة الافتراضية `120.0`) : الحد الأقصى بالثواني للانتظار حتى يصبح صندوق الرمل جاهزًا.

token (`str`، *اختياري*) : تجاوز رمز HF.

أنشئ بيئة اختبار مخصصة (وظيفة HF واحدة) ومنع حتى تصبح جاهزة (حوالي 7 ثوانٍ على cpu-basic).

كل بيئة معزولة هي آلة افتراضية معزولة بالكامل، لذا فهي الخيار الأنسب لأحمال العمل التي تستخدم وحدات معالجة الرسوميات أو الشيفرة غير الموثوقة. أما لتوزيع العديد من بيئات المعالجة المعزولة منخفضة التكلفة على وحدات المعالجة المركزية، فاستخدم [SandboxPool](/docs/huggingface_hub/v2.4.0/ar/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/ar/package_reference/sandbox#huggingface_hub.Sandbox.run)`(..., background=True)`؛ يمكن إيقاف عملية واحدة باستخدام [SandboxProcess.kill()](/docs/huggingface_hub/v2.4.0/ar/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`) : المنفذ (المجموعة: `<port>` من المقبس unix) الذي يستمع عليه الخادم الداخلي.

path (`str`، *اختياري*، القيمة الافتراضية `"/"`) : المسار على الخادم الداخلي الذي يجب توجيه الإشارة إليه، مثل `"/ws"`.

scheme (`str`، *اختياري*، القيمة الافتراضية `"https --//"`): مخطط عنوان URL لبناء الرابط به. القيمة الافتراضية هي `"https://"`؛ مرّر `"wss://"` لعميل WebSocket (الوكيل لا يعتمد على البروتوكول، لذا يتغير مخطط جهة العميل فقط).

**يعيد:** `str`

عنوان URL مثل `https://<job_id>--49983.hf.jobs/v1/.../proxy/8000/ws` (أو `wss://...` مع `scheme="wss://"`).

عنوان URL عام يمرر الطلبات إلى خادم يعمل *داخل* هذه البيئة المعزولة.

تُحوَّل الطلبات الموجَّهة إلى الرابط المُعاد بواسطة خادم العزل داخل المهمة إلى الخادم الذي بدأته داخل بيئة العزل على `port`، بما في ذلك ترقية اتصالات WebSocket (`ws(s)://`) والاستجابات المُبَثَّة. استخدمه مع `proxy_headers` للمصادقة.

يجب أن يستمع صندوق الرمل على `port` على النحو التالي:

- **الحوض / صندوق الرمل المشترك**: لا يمكنه ربط منفذ TCP (Landlock)، لذا اربط **مقبس يونكس** في `$SBX_PROXY_DIR/<port>.sock` (متغير البيئة `SBX_PROXY_DIR` مُعيَّن في كل صندوق رمل). على سبيل المثال `uvicorn app:app --uds $SBX_PROXY_DIR/8000.sock`.
- **بيئة معزولة مخصصة**: اربط منفذ TCP عاديًا على `127.0.0.1:<port>`. (يمكنك أيضًا كشف المنفذ مباشرةً عبر وكيل المهمة دون المرور عبر هذه الطريقة.)

مثال:
```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`، *اختياري*) : البيانات التي سيتم كتابتها إلى مدخل الأمر (stdin).

on_stdout (`Callable[[str], None]`، *اختياري*) : استدعاء يُستدعى مع مقاطع stdout عند وصولها.

on_stderr (`Callable[[str], None]`، *اختياري*) : استدعاء يُستدعى مع مقاطع stderr كلما وصلت.

check (`bool`، *اختياري*، القيمة الافتراضية `True`) : إذا كانت القيمة True، فسيتم رفع `SandboxCommandError` عند انتهاء العملية برمز غير صفري.

capture_output (`bool`، *اختياري*، القيمة الافتراضية `True`) : إذا كانت القيمة True، يتم تجميع stdout/stderr في النتيجة المُعادَة. مرّر `False` إذا كنت تريد فقط `on_stdout`/`on_stderr`: في هذه الحالة، يُسلَّم المخرجات إلى الدوال المستدعاة ثم يُتخلّى عنها، فلا يتعين على الأمر الذي ينتج جيجابايتات أن يتسع في الذاكرة. تكون `result.stdout`/`result.stderr` فارغة في هذه الحالة.

background (`bool`، *اختياري*، القيمة الافتراضية `False`) : إذا كانت القيمة True، ابدأ الأمر بشكل منفصل وأعد [SandboxProcess](/docs/huggingface_hub/v2.4.0/ar/package_reference/sandbox#huggingface_hub.SandboxProcess) فورًا بدلاً من الانتظار وإرجاع [SandboxCommandResult](/docs/huggingface_hub/v2.4.0/ar/package_reference/sandbox#huggingface_hub.SandboxCommandResult).

نفّذ أمرًا في بيئة العزل وانتظر اكتماله، مع بث المخرجات مباشرةً.

عند استخدام `background=True`، يبدأ الأمر بشكل منفصل ويعيد `run` كائن [SandboxProcess](/docs/huggingface_hub/v2.4.0/ar/package_reference/sandbox#huggingface_hub.SandboxProcess) فورًا دون انتظار انتهائه — وهو أمر مفيد للخوادم وغيرها من العمليات طويلة الأمد. يمكنك لاحقًا عرض قوائم بها باستخدام [Sandbox.processes()](/docs/huggingface_hub/v2.4.0/ar/package_reference/sandbox#huggingface_hub.Sandbox.processes) وإيقاف أحدها باستخدام [SandboxProcess.kill()](/docs/huggingface_hub/v2.4.0/ar/package_reference/sandbox#huggingface_hub.SandboxProcess.kill). لا تنطبق خيارات البث/الانتظار فقط (`timeout`، `stdin`، `on_stdout`، `on_stderr`، `check`) في هذا الوضع.

يعيد: [SandboxCommandResult](/docs/huggingface_hub/v2.4.0/ar/package_reference/sandbox#huggingface_hub.SandboxCommandResult) (مع `exit_code`، `stdout`، `stderr`، `duration_ms`)، أو [SandboxProcess](/docs/huggingface_hub/v2.4.0/ar/package_reference/sandbox#huggingface_hub.SandboxProcess) عندما يكون `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)
```

[المصدر](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/_sandbox.py#L1313)

أسطول من مهام "المضيف" المشتركة، حيث يحتوي كل منها على العديد من الصناديق الرملية المعزولة عبر landlock.

> [!WARNING]
> واجهة برمجة التطبيقات الخاصة بـ Sandbox تجريبية. قد تتغير واجهتها وسلوكها دون إشعار مسبق.
>
> **صناديق الرمل المجمّعة مخصصة لأحمال العمل داخل حدّ ثقة واحد.** صندوق الرمل المجمّع هو معرّف مستخدم (uid) بالإضافة إلى مجموعة قواعد Landlock داخل آلة افتراضية مشتركة — وليس آلة افتراضية مستقلة — وكل صناديق الرمل على مضيف واحد تتشارك رمز المصادقة الخاص بذلك المضيف ومستوى التحكم المميز. استخدم مجمّعًا لنشر *كودك الخاص* بتكلفة منخفضة. بالنسبة لأحمال العمل التي لا تثق ببعضها البعض، استخدم [Sandbox.create()](/docs/huggingface_hub/v2.4.0/ar/package_reference/sandbox#huggingface_hub.Sandbox.create)، والذي يمنح كل واحد منها آلة افتراضية خاصة به. تُدرج الفجوات المحددة تحت عنوان "القيود المعروفة" في الدليل المفاهيمي لصناديق الرمل.

المضيف الواحد يمثل مهمة HF واحدة تُحتسب عليها الرسوم (آلة افتراضية)؛ وهو يشغّل خادم البيئة المعزولة ويدير حتى `sandboxes_per_host` من البيئات المعزولة الخفيفة، معزولةً عن بعضها البعض عبر uid و Landlock LSM. وهذا يجعل التوسع الواسع (fan-outs) منخفض التكلفة (حيث تُشارك تكلفة الآلة الافتراضية بين جميع بيئاتها المعزولة) وسريعًا (فإنشاء بيئة معزولة يستغرق تقريبًا ذهابًا وإيابًا واحدًا عبر الوكيل بمجرد أن يصبح المضيف جاهزًا). وهو الأنسب للعديد من بيئات المعالجة المتوازية التي تعتمد على وحدة المعالجة المركزية، مثل عمليات RL rollouts؛ أما إذا كنت بحاجة إلى وحدات معالجة رسومية أو إلى عزل قوي على مستوى الآلة الافتراضية بين أحمال العمل التي لا تثق ببعضها البعض، فاستخدم [Sandbox.create()](/docs/huggingface_hub/v2.4.0/ar/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/ar/package_reference/sandbox#huggingface_hub.Sandbox.connect) — يجب ألا يؤدي مغادرة كتلة `with` إلى تفكيكهم. قم بإنهاء مضيفي المجموعة المتصلة صراحةً باستخدام `hf sandbox pool delete <id>`.

يتم إلغاء المضيفات التي *تعاملت معها فقط*. قد يكون المضيف المكتشف عبر التسميات في خدمة صناديق رملية تابعة لعملية أخرى، لذا يتم تحريره بدلاً من إنهائه.

يرفع `SandboxError` إذا تعذّر إلغاء مهمة مضيف، مع ذكر أسماء المهام التي لا تزال قيد التشغيل — إذ تستمر في الاحتساب، وتُحفظ إدخالات ذاكرتها المؤقتة لتبقى قابلة للاكتشاف. أما إذا تم الوصول إلى `close()` عبر `__exit__` بينما لا يزال استثناء قيد المعالجة، فيُسجَّل الفشل بدلاً من ذلك، حتى لا يُخفي الخطأ الأصلي.

#### اتصال[[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`) : المعرّف الذي يُعاد عند إنشاء المسبح لأول مرة.

namespace (`str`، *اختياري*) : مساحة الأسماء التي سيتم البحث فيها عن مضيفي المسبح (الافتراضي هو مساحتك).

adopt_hosts (`str`، *اختياري*، القيمة الافتراضية `"own"`) : أي مضيفين يمكن إرفاقهم. راجع [SandboxPool](/docs/huggingface_hub/v2.4.0/ar/package_reference/sandbox#huggingface_hub.SandboxPool). يتطلب إعادة الإرفاق بحوض بدأ مضيفوه عضو آخر من مساحة الاسم `"namespace"`.

token (`str`، *اختياري*) : تجاوز رمز HF.

إعادة الاتصال بحوض قيد التشغيل عبر المعرّف، من أي جهاز — دون الحاجة إلى حالة محلية.

يجد مضيفًا قيد التشغيل يحمل التسمية `pool_id` ويعيد بناء إعدادات المجموعة (الصورة/النوع/الكثافة/خمول المضيف) من مواصفات متغيرات البيئة الخاصة بمهمة ذلك المضيف، ويعيد [SandboxPool](/docs/huggingface_hub/v2.4.0/ar/package_reference/sandbox#huggingface_hub.SandboxPool) جاهزًا لاستدعاء `create()` لإنشاء المزيد من البيئات العازلة — إما بتعبئة المضيفات قيد التشغيل، أو بتشغيل نسخة مكررة (بنفس الإعدادات) عند امتلائها.

يرفع `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`) : مهلة الخمول لكل بيئة معزولة — تُستبعد البيئة المعزولة من مضيفها بعد هذه المدة من عدم النشاط (لا توجد استدعاءات لواجهات برمجة التطبيقات، ولا توجد عملية قيد التشغيل). وهي مختلفة عن مهلة خمول المضيف. مرّر `None` لتعطيلها.

forward_hf_token (`bool`، *اختياري*، القيمة الافتراضية `False`) : إذا كانت القيمة True، يتم حقن رمز HF الخاص بك كـ `HF_TOKEN` في بيئة العزل (بانتساب اختياري). على عكس `secrets` في بيئة العزل المخصصة، تُسلَّم متغيرات البيئة في بيئة العزل المشتركة إلى الخادم المضيف عند الإنشاء (ولا تُخزَّن أبدًا في مهمة المضيف)، لذا لا تظهر في بيانات وصفية أي مهمة.

أنشئ صندوق رمل واحدًا، مع توفير مضيف عند الحاجة.

يعيد استخدام مضيف لديه سعة متاحة (سواء كان من هذا المسبح، أو مضيفًا دافئًا تم العثور عليه عبر وسوم المهمة/الذاكرة المؤقتة المحلية) قبل تشغيل مضيف جديد، بحيث يكلف استدعاء `create()` على مضيف دافئ تقريبًا ذهابًا وإيابًا واحدًا. استدعه بشكل متكرر لتوزيع المهام؛ واستخدم `warm_up` (أو `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` مضيفًا فارغًا قيد التشغيل واتركها تعمل. تُرجع معرفات مهام المضيفين في المسبح.

يُستخدم لإنشاء مجموعة مسبقًا: حيث تحمل العُقد تسمية المجموعة وإعداداتها (في متغيرات البيئة الخاصة بها)، وبالتالي فإن استدعاء `SandboxPool.connect(pool_id)` لاحقًا (حتى من جهاز آخر) سيجدها ويطلق بيئات العزل دون بدء بارد. وتبقى العُقد محاسبةً حتى يتم إيقافها أو تصبح خاملة.

يتبنى العُقد التي تعمل بالفعل لهذا المسبح (عبر وسمات المهمة) قبل بدء التشغيل، بحيث يؤدي استدعاء `warm()` بعد `connect()` — أو استدعاء `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/ar/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/ar/package_reference/sandbox#huggingface_hub.Sandbox.run)`(..., background=True)`.

استعرض عمليات بيئة العزل باستخدام [Sandbox.processes()](/docs/huggingface_hub/v2.4.0/ar/package_reference/sandbox#huggingface_hub.Sandbox.processes) وأوقف إحداها باستخدام [SandboxProcess.kill()](/docs/huggingface_hub/v2.4.0/ar/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 : حالة HTTP التي يعيدها الخادم داخل بيئة العزل، إذا كان الخطأ ناجمًا عن استجابة واجهة برمجة التطبيقات (مثل `404` لملف مفقود). `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, ...).

تُستدعى هذه الاستثناءات عندما ينتهي تنفيذ أمر داخل بيئة معزولة برمز غير صفري.