# 映像

機器啟動所用的映像，可以是預裝 SSH 和常用工具的 Arrakis 映像，也可以是你自己的映像（公開或私有均可）。

## Arrakis 映像

除非你另選映像，機器預設啟動 Arrakis 映像。每個 Arrakis 映像都基於官方基礎映像，並加入了 SSH、登入橫幅和日常工具：git、git-lfs、tmux、htop、nvtop、rsync、curl、wget、jq 和一個編輯器。在每個 SSH 會話裡，Python 都已在 PATH 中。

| 映像 | 包含內容 | Docker 映像 |
|---|---|---|
| PyTorch 2.14（預設） | PyTorch 2.14.1, CUDA 13.0, Python 3.12, Ubuntu 24.04 | `goodailabs/arrakis:pytorch-2.14.1-cuda13.0` |
| 帶有 CUDA 工具包的 PyTorch 2.14 | 同上，另加 nvcc、CUDA 標頭檔案和編譯器 | `goodailabs/arrakis:pytorch-2.14.1-cuda13.0-devel` |
| CUDA 13.0 工具包 | CUDA 13.0.3、cuDNN 9、nvcc、Python 3.12、Ubuntu 24.04 | `goodailabs/arrakis:cuda-13.0.3-devel` |
| Ubuntu 26.04 | Python 3.14。GPU 驅動由機器提供 | `goodailabs/arrakis:ubuntu-26.04` |

CUDA 13.0 正是 `pip install torch` 安裝的版本，因此為 PyTorch 構建的 wheel 可以直接使用。它能在 Arrakis 的每臺機器上執行，包括 Blackwell：每臺機器的 NVIDIA 驅動都是 580 系列或更新版本。這些映像在 Docker Hub 上公開，你也可以在自己的電腦上拉取同一個映像；預設映像是 `goodailabs/arrakis:latest`。

登入時會顯示機器的 GPU、映像和可用磁碟空間：

```text
  6 × NVIDIA RTX A4000, 16 GB each
  PyTorch 2.14.1, CUDA 13.0, Python 3.12.3, Ubuntu 24.04.5 LTS
  32 CPU cores, 125 GB memory, 412 GB free in /workspace
```

請在 `/workspace` 中工作。機器停止時，其上的所有內容（包括 `/workspace`）都會被刪除。

## 你自己的映像

任何映像都可以：vLLM、SGLang、NVIDIA NGC 容器，或你們團隊自己的映像，公開或私有均可。

- 在 **Images** 頁面選擇 **Add an image**，按 `docker pull` 接受的格式貼上映像名，例如 `vllm/vllm-openai:v0.11.0`。如果是公開映像，也可以在租用時選擇 **Your own image**。
- Arrakis 會先向映像所在的映像倉庫確認：映像必須存在、可以拉取，並且有 linux/amd64 版本。拼寫錯誤或權杖有誤時，會在扣費之前就被拒絕。
- 支援的映像倉庫：Docker Hub、GitHub（`ghcr.io`）、Amazon ECR 和 ECR Public、Google（Artifact Registry 和 `gcr.io`）、Azure（`azurecr.io`）、NVIDIA NGC（`nvcr.io`）、Quay、GitLab 和 Microsoft（`mcr.microsoft.com`），也可以是你自己的：Harbor、Artifactory、Nexus、自託管的 GitLab 或 Quay，以及任何可透過公網 DNS 名稱訪問的映像倉庫，例如 `registry.example.com:5000/team/app:v1`。
- 啟動時會為任何映像加上 SSH，所以你始終以同樣的方式用 root 登入。映像中需要有 shell。
- 在一臺機器上首次啟動時會下載映像。映像越大，耗時越長：在慢速網路上，12 GB 的映像可能需要 10 到 20 分鐘。

### 私有映像

新增映像時勾選 **It's private: log in to pull it**，並填寫 `docker login` 所需的登入憑據。Arrakis 會在儲存前用它核驗映像，加密儲存，並且只在你租用時用它拉取這個映像。密碼之後不會再顯示。

| 映像倉庫 | 使用者名稱 | 密碼或權杖 |
|---|---|---|
| Docker Hub | 你的 Docker Hub 使用者名稱 | 具有隻讀許可權的個人訪問權杖 |
| GitHub（`ghcr.io`） | 你的 GitHub 使用者名稱 | 只帶 `read:packages` 許可權的經典權杖（classic） |
| Amazon ECR（`<account>.dkr.ecr.<region>.amazonaws.com`） | 訪問金鑰 ID | 對應的秘密訪問金鑰 |
| Google（`<region>-docker.pkg.dev`、`gcr.io`） | `_json_key` | 具有 Artifact Registry Reader 角色的服務帳號 JSON 金鑰 |
| Azure（`<name>.azurecr.io`） | 儲存庫權杖或服務主體 | 對應的密碼，僅有拉取許可權 |
| NVIDIA NGC（`nvcr.io`） | `$oauthtoken` | 你的 NGC API 金鑰 |
| GitLab（`registry.gitlab.com`） | 部署權杖的使用者名稱 | 部署權杖，需帶 `read_registry` 許可權 |
| Quay | 機器人帳戶 | 對應的權杖 |
| 你自己的映像倉庫 | 它要求的使用者名稱 | 對應的密碼或權杖 |

- **Amazon ECR**：使用一個只能拉取映像的 AWS 使用者（`AmazonEC2ContainerRegistryReadOnly` 策略）。每次租用時，Arrakis 都會用金鑰換取一個新的、有效期 12 小時的拉取登入憑據（即 `aws ecr get-login-password` 輸出的那個），因此機器永遠接觸不到金鑰本身。
- **你自己的映像倉庫**：機器無論位於何處都會直接從它拉取，因此它必須能在公網上透過 HTTPS 訪問，並使用公共證書頒發機構（例如 Let's Encrypt）簽發的證書。位於 VPN 或 IP 允許列表之後的映像倉庫無法訪問；使用自簽名證書的會被拒絕。
- 請使用只讀權杖。機器會用它拉取映像，而租用結束後映像可能仍快取在那臺機器上，所以不要把機密資訊放進映像，而是在執行時再傳入。
- 要更換權杖，點選映像旁邊的 **Change login**，或用新權杖重新儲存同一個映像。移除映像時，Arrakis 會在所有儲存過其登入憑據的地方將其刪除。

### 啟動時的行為

| 選項 | 執行內容 | 適用場景 |
|---|---|---|
| Wait for me to log in（預設） | 什麼都不執行，機器會等你登入 | 訓練、notebook，以及任何你透過 SSH 啟動的任務 |
| Run the image's command | 映像自帶的 entrypoint 和命令 | vLLM、TGI 或 SGLang 等伺服器 |
| Run a command | 你提供的一行普通命令，例如 `python -m http.server 8000` | 自動開始的任務 |

如果命令退出，機器就無法再訪問。拿不準時，請選擇 **Wait for me to log in**。

透過 SSH 訪問機器上的伺服器：

```sh
ssh -L 8000:localhost:8000 root@<host> -p <port>
curl localhost:8000/v1/models
```

### 環境變數

為映像新增 `KEY=value` 鍵值對，每行一個。它們會隨映像一起儲存，所以不要在這裡放機密資訊，而應透過 SSH 設定，例如在會話中執行 `export HF_TOKEN=...`。

## 透過 CLI、API 和 AI 代理使用

```sh
arrakis images list
arrakis images add vllm/vllm-openai:v0.11.0 --start image
arrakis instances create --node-id <node> --image vllm/vllm-openai:v0.11.0 --start image --termination-hours 2
```

私有映像需要提供登入憑據，權杖按 `docker login` 的方式從 stdin 傳入：

```sh
echo "$GITHUB_TOKEN" | arrakis images add ghcr.io/acme/trainer:v3 --username acme-bot --password-stdin
arrakis instances create --node-id <node> --template-id <image id> --termination-hours 2
```

```sh
curl -X POST $ARRAKIS_URL/v1/instances -H "Authorization: Bearer $ARRAKIS_TOKEN" -H "Content-Type: application/json" \
  -d '{"node_id": "<node>", "name": "vllm", "termination_hours": 2, "ssh_public_key": "ssh-ed25519 AAAA...",
       "image": "vllm/vllm-openai:v0.11.0", "start": "image"}'
```

- `GET /v1/templates` 列出 Arrakis 映像和你的映像；`POST /v1/templates` 儲存一個映像（`image`、`start`、`command`、`environment`，私有映像還需 `registry_username` 和 `registry_password`）。密碼只能寫入：響應中顯示的是 `private` 和 `registry_username`。用 `PATCH /v1/templates/{id}` 同時提交這兩個欄位即可替換登入憑據。
- `POST /v1/instances` 啟動 `template_id` 指定的映像，或任意公開 `image`（需帶 `start`）。
- 透過 MCP 時，`list_images` 會列出這些映像並標出私有映像，`rent_gpu` 接受 `template_id` 或 `image`。

更多：[全部文件](/zh-tw/docs.md) · [OpenAPI](/openapi.json) · [llms.txt](/zh-tw/llms.txt)