> ## Documentation Index
> Fetch the complete documentation index at: https://datagen.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 沙箱環境（Sandbox Environments）

> 把基礎映像檔、套件與內部套件來源預先建置成可重複使用的映像檔，讓 Agent、知識庫與應用（App）啟動時就已備妥所需的一切

每次 Agent 執行、知識庫建置與應用（App）都會在獨立的 DataGen **沙盒**中執行程式碼。**沙箱環境**是這個沙盒的可重複使用配方：基礎映像檔加上 `apt` / `pip` / `uv` / `npm` 套件、選填的內部套件登錄檔，以及 CPU / 記憶體 / 磁碟規格。

DataGen 會在背景把配方建置成映像檔。綁定此環境的項目都會從建置好的映像檔啟動，因此執行時不需安裝任何東西，每次執行看到的套件版本也都相同。

<Frame>
  <img src="https://mintcdn.com/datagen/rusBmwP8bd_Srmdm/images/data-agent/sandbox-environments-list.png?fit=max&auto=format&n=rusBmwP8bd_Srmdm&q=85&s=27d9744c36153f68a49c6bb64e250ea6" alt="沙箱環境列表，每個環境顯示其預先建置的套件組合" width="1798" height="838" data-path="images/data-agent/sandbox-environments-list.png" />
</Frame>

## 開啟沙箱環境

在左側欄開啟 **更多** 選單，選擇 **沙箱環境**。點選 **釘選到側邊欄** 可讓它固定顯示在側邊欄上。

<Note>
  若選單中沒有 **沙箱環境**，代表你的帳號尚未啟用此功能，Agent 會在標準映像檔上執行。請聯絡 DataGen 啟用。
</Note>

管理員與建構者可以建立、編輯和刪除環境。所有成員都可以檢視。

***

## 建立環境

<Steps>
  <Step title="開啟對話框">
    點選 **新增環境**。
  </Step>

  <Step title="選擇性地從範本開始">
    在 **Start from template (optional)** 選擇範本，它會預先填入套件；建立前你可以修改任何內容。
  </Step>

  <Step title="命名並列出套件">
    輸入 **名稱**，再填入你需要的套件欄位。
  </Step>

  <Step title="建立">
    點選 **建立**。建置會在背景開始，卡片上會顯示進度。
  </Step>
</Steps>

<Frame>
  <img src="https://mintcdn.com/datagen/rusBmwP8bd_Srmdm/images/data-agent/sandbox-new-environment.png?fit=max&auto=format&n=rusBmwP8bd_Srmdm&q=85&s=67ff74418f9fca9b197c686ca1777d76" alt="新增環境對話框，從 Data Engineering 範本開始" width="638" height="833" data-path="images/data-agent/sandbox-new-environment.png" />
</Frame>

### 內建範本

| 範本 | pip 套件 |
| - | - |
| **Data Science** | `pandas`、`numpy`、`scipy`、`scikit-learn`、`matplotlib`、`seaborn`、`polars`、`pyarrow`、`openpyxl`、`statsmodels` |
| **Data Engineering** | `duckdb`、`polars`、`pyarrow`、`sqlalchemy`、`psycopg2-binary`、`pandas` |
| **Web Scraping & HTTP** | `requests`、`httpx`、`beautifulsoup4`、`lxml` |
| **Documents & Files** | `openpyxl`、`python-docx`、`pypdf`、`pillow`、`markdown`、`pandas` |

範本會被複製到新環境中。之後修改環境不會改動範本，反之亦然。

### 欄位

| 欄位 | 用途 |
| - | - |
| **名稱** | 必填。顯示在所有環境選擇器中。 |
| **描述** | 選填。顯示在卡片上；使用範本時會自動填入套件清單。 |
| **基礎映像檔（選填）** | 自訂基礎映像檔，例如 `python:3.11-slim`。僅適用於 Daytona；Modal 使用內建的 Debian 基礎環境，`apt` / `pip` / `uv` / `npm` 皆可運作。 |
| **apt 套件** | 系統套件，例如 `ffmpeg libpq-dev`。 |
| **pip 套件** | 以 pip 安裝的 Python 套件。 |
| **uv 套件** | 以 uv 安裝的 Python 套件（比 pip 快）。 |
| **npm 套件** | Node 套件。 |
| **內部登錄檔（選填）** | **pip / uv 索引網址**、**npm 登錄檔網址** 與 **apt sources.list**，用於從私有鏡像或套件庫安裝。網址必須是 `http://` 或 `https://`。 |
| **資源配置（選填）** | **CPU 核心數**（1 或 2）、**記憶體**（1 GB 或 2 GB）、**磁碟**（2 GB 或 5 GB，僅限 Daytona）。**預設** 使用下拉選單中顯示的部署預設值。 |
| **工作區預設** | 把此環境標記為工作區預設。它會排在選擇器最前面，並標示 **（預設）**。 |

套件清單可用空格、逗號或換行分隔。指定版本時不要加空格，例如 `pandas==2.2.2`、`psycopg[binary]` 或 `@scope/tool@1.4.0`。

<Note>
  **Modal 與 Daytona。** DataGen 雲端版在 Modal 上執行沙盒；地端部署使用 Daytona。在 Modal 上，**基礎映像檔** 與 **磁碟** 設定會被忽略。在 Daytona 上，資源配置是映像檔本身的一部分，因此變更資源配置會重新建置映像檔。
</Note>

***

## 建置狀態

只要建置輸入（基礎映像檔、套件、登錄檔或資源配置）有變更，DataGen 就會重新建置映像檔。每張卡片會顯示 **代理** 建置狀態標籤：

| 狀態 | 意義 |
| - | - |
| **待處理** | 已排入佇列，建置即將開始。 |
| **建置中** | 映像檔建置中，進度條會顯示已經過的時間。 |
| **就緒** | 映像檔已建置完成，執行可以從它啟動。 |
| **失敗** | 建置失敗。卡片會顯示 `建置失敗：<error>` -- 通常是套件名稱拼錯或指定了不存在的版本。編輯環境修正後儲存，就會開始新的建置。 |

筆記本應用使用由同一份配方建置的獨立 **筆記本** 映像檔。請求建置後才會顯示它的標籤；在卡片上點選 **建置筆記本映像檔**（或 **重試筆記本建置**）。筆記本沙盒一律至少有 10 GB 磁碟。

列表下方的 **應用程式映像檔** 表格，顯示每個自訂應用在儲存時建置的相依套件映像檔。它們由應用管理；沒有任何有效版本使用的映像檔可以在此刪除。

***

## Agent、知識庫與應用如何使用環境

| 位置 | 設定 | 映像檔尚未就緒時 |
| - | - | - |
| **Agent** | **沙箱環境** 卡片 -> **環境**，再點 **儲存環境** | 執行會**拒絕啟動**，並顯示 `Sandbox environment image is not ready (build status: ...)`。 |
| **知識庫建構器** | 知識庫設定 -> **沙箱環境** | 建置完成前，建構器會從標準映像檔啟動。變更會在建構器工作階段下次冷啟動時生效。 |
| **筆記本應用** | App 建構器 -> **沙箱** | 綁定前，環境的 **筆記本** 映像檔必須已就緒。 |
| **自訂應用** | App 建構器 -> **沙箱** | 變更後會在新環境上重新建置應用的相依套件映像檔，再重新建立沙盒。 |
| **資料建構器** | 資料 -> **建構器設定** -> **沙箱環境** | -- |

Agent 若保持 **預設（標準映像檔）**，就會在 DataGen 的標準映像檔上執行。

***

## 常見問題

<AccordionGroup>
  <Accordion title="編輯環境後 Agent 執行立刻失敗">
    任何對套件、登錄檔、基礎映像檔或資源配置的變更都會觸發重新建置，在重新 **就緒** 前，綁定此環境的 Agent 都會拒絕執行。請在沒有排程執行的時段修改，或等標籤變成綠色。
  </Accordion>

  <Accordion title="刪除環境">
    使用它的 Agent 會改用標準映像檔 -- 不含它的套件。若 Agent 的程式碼會匯入其中的套件，請先把它們改綁到其他環境。
  </Accordion>

  <Accordion title="改在執行時安裝">
    只要沙盒有對外網路，程式碼仍可在沙盒內 `pip install`，但每次執行都要付出安裝時間，且不同次執行之間可能出現版本差異。會重複使用的套件請預先建置。
  </Accordion>

  <Accordion title="Alpine / musl 基礎映像檔">
    許多二進位 wheel（例如 `psycopg2-binary`）只提供 glibc 版本。在 musl 基礎映像檔上，請選擇有提供 musl wheel 的套件（例如 `psycopg[binary]`）。
  </Accordion>
</AccordionGroup>

## 下一步

<CardGroup cols={2}>
  <Card title="Harness" icon="gear" href="/zh/foundation/harness">
    選擇 Agent 執行環境、鎖定版本，並把它導向你自己的 LLM 閘道。
  </Card>

  <Card title="從程式碼查詢資料庫" icon="database" href="/zh/data/query-from-code">
    使用 Data Engineering 範本的實作範例。
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.