Vault 儲存空間

GPUtw Vault 儲存空間會掛載到運行中 GPU 容器的 /vault。請用它保存需要跨 session 保留的資料集、checkpoint、模型權重與輸出。

容器 workspace 綁定於所選工作節點與執行個體生命週期。Vault 是用來保存跨工作階段檔案的持久化區域。若餘額為 NT$0 或以下，Vault 資料會保留 30 天，若未儲值則刪除。

該寫到哪一個，取決於檔案的性質：

• /vault: 資料集、訓練檢查點、模型權重——任何需要比執行個體活得更久的東西。屬於網路儲存，帳號下每個執行個體都看得到。
• /workspace: 安裝環境（pip、conda、npm）、編譯、解壓縮含上萬個小檔案的壓縮檔。這是執行個體自己的磁碟——這類工作在此較快，但會隨執行個體一併刪除，值得保留的成果請複製到 /vault。

請將生成的 checkpoint、下載的資料集與專案成果放在 /vault。避免在共享 notebook 或公開 web 目錄中存放密鑰。

在控制台的 Vault 頁面，你可以瀏覽資料夾、拖放上傳（大檔案會以可續傳的分段方式上傳，沒有 100 MB 限制），也可以用「從網址下載」讓伺服器直接把模型抓進你的 Vault——不需開機器、不需終端機。貼上直接連結或 Hugging Face 參照，並選擇目標資料夾即可。

控制台的拖放區負責瀏覽器端的上傳。要從 CI、腳本或另一台機器把檔案送進來，共有四種方式；選哪一種取決於兩個問題：需不需要一台執行中的機器，以及檔案要不要比執行個體活得久。

• 直接上傳到 /vault: 一個 HTTPS 請求搭配上傳權杖。不需要執行個體，也不產生任何運算費用。CI、排程工作，以及從你原本就有的伺服器推送，都用這一種。
• 可續傳的分段上傳: 目的地相同，適用於超過約 90 MB 的檔案，或任何可能中斷的連線。單檔上限 2 TB。
• SCP 到 /vault: 需要一台 RUNNING 的執行個體；檔案在該執行個體刪除後仍然保留。
• SCP 到 /workspace: 需要一台 RUNNING 的執行個體；檔案會隨執行個體一起消失，但訓練過程反覆讀取的資料放這裡比較快。

直接上傳到 Vault——免開機。請在控制台 → API 金鑰選擇「上傳權杖」組合。它只授予 vault:write，因此在完全沒有執行個體的情況下就能透過 HTTPS 寫入 /vault；即使權杖從 CI 記錄外洩，也無法部署執行個體、無法啟動 GPU 花費，更讀不到、下載不了任何一個檔案——列出與下載屬於 vault:read，而這個組合並不包含它。

curl -X POST "https://upload.gputw.ai/api/vault/upload?path=datasets" \
  -H "Authorization: Bearer gputw_live_..." \
  -F "[email protected]"

• ?path=: Vault 內的目標資料夾。可以是多層路徑，不存在時會自動建立，省略則寫入 Vault 根目錄。它指的是資料夾而不是檔名——檔名取自上傳的檔案本身。
• file: multipart 表單的欄位名稱，必須完全是這個名字。
• 回應: 201，並在慣用的 data 外層回傳建立的項目：name、size、modifiedAt、type。

檔案超過約 90 MB，或連線品質不足以賭上一次 40 GB 的傳輸時，請改用下一節的可續傳 API。控制台的拖放區也是在同一個門檻自動切換的。

分段上傳 API 會把一個檔案切成多個 part，各自以獨立請求送出。任何單一請求都遠低於 body 大小限制，連線中斷只損失一個 part 而不是整趟傳輸，單檔最大可到 2 TB——再往上，真正的限制是你的 Vault 配額，而它在建立 session 時就會檢查，並把你其他還在進行中的 session 一併計入。

共四個步驟：建立 session、逐一 PUT 各個 part、呼叫 complete，然後在伺服器合併期間輪詢狀態。

# 1 — 建立 session。這裡的 path 要「包含檔名」。
curl -X POST "https://upload.gputw.ai/api/vault/uploads" \
  -H "Authorization: Bearer gputw_live_..." \
  -H 'Content-Type: application/json' \
  -d '{"path":"models/model.safetensors","size":21474836480}'
# → 201 {"success":true,"data":{"uploadId":"<uuid>","chunkSize":16777216,
#        "partCount":1280,"status":"pending", ...},"error":null}

# 2 — 依 session 回傳的 chunkSize 切檔，再逐一 PUT。
#     直接送原始位元組，編號從 0 開始，不要包成 multipart。
split -b 16777216 -d -a 4 model.safetensors part-
curl -X PUT "https://upload.gputw.ai/api/vault/uploads/<uploadId>/parts/0" \
  -H "Authorization: Bearer gputw_live_..." \
  -H 'Content-Type: application/octet-stream' \
  --data-binary @part-0000

# 3 — 所有 part 都送達後呼叫 complete。回應 202，合併在背景進行。
curl -X POST "https://upload.gputw.ai/api/vault/uploads/<uploadId>/complete" \
  -H "Authorization: Bearer gputw_live_..."

# 4 — 輪詢直到 status 變成 completed（或 failed）。
curl -H "Authorization: Bearer gputw_live_..." \
  "https://upload.gputw.ai/api/vault/uploads/<uploadId>"

• path: 相對於 Vault 根目錄，且必須包含檔名——這一點與上面的單一請求上傳不同。不可指向已經存在的資料夾。
• size: 檔案的精確位元組長度，上限 2 TB。每個 part 的大小都以它為基準檢查，因此不能是估計值。
• sha256: 選填，64 個十六進位字元。伺服器會在合併時一併計算雜湊，不符即讓這次上傳失敗，並保留已暫存的 part 供你重送。
• chunkSize: 選填，介於 4 MiB 與 64 MiB，預設 16 MiB。線路快的話可以用較大的 part 換較少的請求；線路慢則不建議，因為每個 part 仍必須在單一請求內傳完。
• part 編號: 從 0 開始，到 partCount - 1。除了最後一個 part 是餘數之外，每個 part 都必須剛好是 chunkSize 位元組——超過會被回以 413。

控制台的拖放區走的就是這一套流程，所以瀏覽器上傳大檔案時，即使連線不穩也不需要你做任何事。

Vault 的傳輸另有一個專屬主機，直接連到我們的儲存空間，不經過網站前方的 CDN。對大檔案來說有兩個關鍵差異：單一請求不再有 100 MB 上限，數 GB 的傳輸也快得多。其餘完全相同——同樣的 API、同樣的權杖、同樣的路徑，只有主機名稱不同。

# 同一個上傳請求，改送到傳輸主機
curl -X POST "https://upload.gputw.ai/api/vault/uploads" \
  -H "Authorization: Bearer gputw_live_..." \
  -H 'Content-Type: application/json' \
  -d '{"path":"models/model.safetensors","size":21474836480}'

該主機刻意只提供傳輸路由：

• 可用: /api/vault/upload、/api/vault/uploads/…、/api/vault/download、/api/vault/download-zip 與 /api/vault/download-token。
• 其他一律: 回傳 404——登入、列出 Vault 內容、執行個體、帳務都不在這裡。這些請繼續使用主網域，並保留其前方的防護。

控制台的 Vault 頁面已經幫你處理好了：拖放區會自動分段，並在有傳輸主機時透過它上傳。

控制台檔案瀏覽器使用的端點，同樣開放給帶有 vault:read 的 API 金鑰。所有路徑都相對於您的 Vault 根目錄。

回傳 files[]，每項包含 name、size、modifiedAt 與 type（file 或 directory）。有兩點請在程式中預先處理：

• size 可能為 null: 目錄才會出現。只有根目錄列表會附上遞迴總計，且即使在根目錄，取不到總計時仍為 null。請把 null 當成「未知」，絕不可當成 0。
• 列表不會遞迴: 要走完整棵樹，請逐一資料夾呼叫。

以 application/octet-stream 串流單一檔案，並帶 RFC 6266 的 Content-Disposition，因此中文等非 ASCII 檔名不會損壞。支援 byte range，大檔案下載因此可以續傳：

# 續傳中斷的 40 GB 模型下載
curl -fSL -C - -o model.safetensors \
  -H "Authorization: Bearer gputw_live_..." \
  "https://upload.gputw.ai/api/vault/download?filename=models/model.safetensors"

# 或指定單一區段
curl -fsS -r 0-1048575 \
  -H "Authorization: Bearer gputw_live_..." \
  "https://upload.gputw.ai/api/vault/download?filename=models/model.safetensors"

• 206 + Content-Range: 區段有效時回傳；並一律宣告 Accept-Ranges: bytes。
• 416: 區段起點超出檔案結尾時回傳。不會默默改回傳整個檔案——那會讓續傳的檔案損壞。
• 僅支援單一區段: 多重區段的請求會回傳整個檔案，而非 multipart 回應。

將整個資料夾即時打包成一個 .zip 串流輸出，且不壓縮——Vault 內容通常本身已壓縮過，再壓一次只是白費 CPU。符號連結會以連結本身封存，不會跟隨。打包期間被刪除的檔案會跳過，不會讓整個下載失敗。

SCP 與 rsync 透過 SSH 閘道的 2222 連接埠連到執行個體，因此不同於上傳權杖，它需要一台 RUNNING 的執行個體，並先在控制台 → SSH 金鑰加入公開金鑰——閘道會拿你送出的金鑰比對帳號上的金鑰，完全不提供密碼登入。使用者名稱是 pod-<instance-id>，主機是 SSH 閘道，而不是你平常登入的網站。兩個目標路徑差別很大：

• /vault: 網路儲存空間，帳號下所有執行個體共用，且比執行個體活得久。資料集、checkpoint 與訓練完成的權重都應該放這裡：執行個體刪除後檔案仍在，下一台部署的機器也看得到同一批檔案。
• /workspace: 執行個體自己的磁碟——訓練過程反覆讀取的資料放這裡比較快，但會隨執行個體一起銷毀。任何值得保留的成果，都必須在刪除前複製到 /vault。

# 單一檔案送進 /vault
scp -P 2222 train.zip pod-<instance-id>@ssh.gputw.ai:/vault/datasets/

# 整個資料夾——加 -r，與一般 scp 相同
scp -P 2222 -r ./project pod-<instance-id>@ssh.gputw.ai:/workspace/

傳輸可能中斷或需要重複同步時，請改用同一個閘道上的 rsync——它會從中斷處接續，也會略過已經存在的檔案：

rsync -avP -e 'ssh -p 2222' ./dataset/ pod-<instance-id>@ssh.gputw.ai:/vault/datasets/