# 部署模型

用 vLLM、SGLang、vLLM-Omni 或 llama.cpp 和你自己的引擎引數執行任何 Hugging Face 模型（文字、影象、影片或語音）：有專屬 API 金鑰的 OpenAI 相容端點，以及 root SSH。

## 在控制台中檢視

1. 在[控制台](/console/#/models)中開啟 **Models**。
2. 按 Hugging Face 上的名稱填寫模型，例如 `Qwen/Qwen3-8B`，或直接貼上模型連結。
3. 選擇引擎：文字模型用 **vLLM** 或 **SGLang**，影象和影片模型用 **vLLM-Omni** 或 **SGLang**，語音和聲音用 **vLLM-Omni**，GGUF 檔案用 **llama.cpp**。使用 llama.cpp 時，在冒號後加上量化方式，例如 `unsloth/Qwen3-8B-GGUF:Q4_K_M`。
4. 如果有自己的引擎引數，就貼進去（見下文）。
5. 對於受限（gated）或私有的模型，請新增一個具有讀取許可權的 Hugging Face 權杖。
6. **Find GPUs** 會從 Hugging Face 讀取模型大小，顯示機器將執行的啟動命令，並列出當前所有放得下該模型的 GPU 及其價格。選一個租用即可。

引擎會在機器啟動時下載模型，所以端點幾分鐘後才會響應。**Models** 會顯示它何時就緒、它的地址、API 金鑰、呼叫程式碼、對話和影象模型的試用，以及引擎日誌。

## 你自己的引擎引數

把你調好的引數，按你平時儲存的樣子貼進來：

```sh
VLLM_USE_DEEP_GEMM=1 vllm serve Qwen/Qwen3-8B \
  --max-model-len 32768 --enable-prefix-caching \
  --speculative-config '{"method": "eagle3", "num_speculative_tokens": 3}'
```

單獨的引數、完整命令和 `docker run` 命令列都可以，前面的環境變數和加引號的 JSON 值也照常可用。引數由你選擇，並由你隨引擎版本保持更新。Arrakis 不經過 shell 讀取它們，並逐字交給引擎，因此：

- shell 語法（`;`、`|`、`&&`、`$(...)`、`$VARIABLES`）會被拒絕：沒有任何東西會去執行它。
- 引擎的監聽位置（`--host`、`--port`）、金鑰（`--api-key`）和模型由 Arrakis 負責，因此端點的地址和金鑰不會變。`--served-model-name`（llama.cpp 用 `--alias`）可以修改請求中使用的模型名稱。
- 並行方式以你為準：只要引數中有 `-tp`、`--tp` 或 `-dp`，Arrakis 就不再新增自己的設定。
- 選擇 GPU 的設定（`NVIDIA_*`）和載入器設定（`LD_*`）會被拒絕：機器只使用它租用的 GPU。
- Hugging Face 權杖要填在專門的欄位裡，不要放進引數，這樣它就不會和引數一起被儲存。

## 透過 API 使用

```sh
curl -X POST $ARRAKIS_URL/v1/deploy \
  -H "Authorization: Bearer ark_..." \
  -H "Content-Type: application/json" \
  -d '{"model": "black-forest-labs/FLUX.1-schnell", "engine": "omni", "termination_hours": 4,
       "extra_args": "--enforce-eager"}'
```

不指定 `node_id` 時，Arrakis 會在放得下該模型的機器中租用排名最高的一臺，並儘量少用 GPU。`POST /v1/deploy/plan` 會先免費列出所有放得下它的 GPU；帶上 `extra_args` 時，它還會檢查你的引數並返回啟動命令。返回結果包含端點及其 `api_key`；`GET /v1/instances/{id}/endpoint` 會再次給出它們，模型開始響應後 `ready` 為真；`GET /v1/instances/{id}/endpoint/log` 返回引擎日誌的末尾。AI 代理透過 [MCP](/zh-tw/docs/agents) 使用 `deploy_model` 工具。

## 呼叫模型

端點使用 OpenAI API，所以任何 OpenAI 客戶端都能用。請求中的模型名稱就是它在 Hugging Face 上的 ID，不含量化方式，除非你改過名稱。

```python
from openai import OpenAI

client = OpenAI(base_url="http://<address>/v1", api_key="sk-...")
reply = client.chat.completions.create(
    model="Qwen/Qwen3-8B",
    messages=[{"role": "user", "content": "Hello"}],
)
print(reply.choices[0].message.content)
```

| 模型生成的內容 | 呼叫地址 |
|---|---|
| 文字 | `POST /v1/chat/completions`、`/v1/completions`、`/v1/embeddings` |
| 映像 | `POST /v1/images/generations`、`/v1/images/edits` |
| 影片 | `POST /v1/videos`，然後用 `GET /v1/videos/{id}` 查詢直到完成，再用 `GET /v1/videos/{id}/content` 下載 |
| 語音 | `POST /v1/audio/speech` |
| 聲音與音樂 | `POST /v1/audio/generate` |
| 語音轉文字 | `POST /v1/audio/transcriptions` |

## 這臺機器由你掌控

- 它就是一次普通的租用：按小時計費，到移除時間即被移除，並列在 **Instances** 中。
- 它會以基於引擎官方版本構建的 Arrakis 映像啟動，帶 root SSH。可以在機器上執行 `arrakis-serve status`、`arrakis-serve logs` 或 `arrakis-serve restart`。
- 要在不換機器的情況下嘗試其他引數，編輯 `/etc/arrakis/serve/command`（每行一個詞）或 `/etc/arrakis/serve/env`，然後執行 `arrakis-serve restart`。引擎停止時機器仍會執行，方便你修復。
- 端點就是機器的地址，使用普通 HTTP。埠 8000 上的訪問閘道器會在請求到達引擎之前檢查 API 金鑰（`Authorization: Bearer <key>`），而引擎只在機器內部監聽；`/health` 不需要金鑰即可訪問，只說明引擎是否已啟動。如需私密通訊，請開啟 SSH 隧道（`ssh root@<host> -p <port> -N -L 8000:localhost:8000`），然後使用 `http://localhost:8000/v1`。
- 你的 Hugging Face 權杖會以 `HF_TOKEN` 的形式傳給機器，Arrakis 不會儲存它。機器的主機商能讀取其上執行的內容，因此請使用細粒度的只讀權杖。

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