# 部署模型

用 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` 返回引擎日志的末尾。智能体通过 [MCP](/zh-cn/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-cn/docs.md) · [OpenAPI](/openapi.json) · [llms.txt](/zh-cn/llms.txt)