# Implantar um modelo

Sirva qualquer modelo do Hugging Face (texto, imagem, vídeo ou voz) com vLLM, SGLang, vLLM-Omni ou llama.cpp e suas próprias opções do motor: um endpoint no estilo da OpenAI com chave de API própria, e SSH como root.

## No console

1. Abra **Models** no [console](/console/#/models).
2. Informe o nome do modelo como no Hugging Face, por exemplo `Qwen/Qwen3-8B`, ou cole o link dele.
3. Escolha o motor: **vLLM** ou **SGLang** para modelos de texto, **vLLM-Omni** ou **SGLang** para modelos de imagem e vídeo, **vLLM-Omni** para voz e som, **llama.cpp** para um arquivo GGUF. No llama.cpp, adicione a quantização depois de dois-pontos, como `unsloth/Qwen3-8B-GGUF:Q4_K_M`.
4. Cole suas próprias opções do motor, se tiver (veja abaixo).
5. Para um modelo restrito (gated) ou privado, adicione um token do Hugging Face com permissão de leitura.
6. **Find GPUs** lê o tamanho do modelo no Hugging Face, mostra a linha de início que a máquina vai rodar e lista todas as GPUs em que ele cabe agora, com o preço. Escolha uma e alugue.

O motor baixa o modelo quando a máquina inicia, então o endpoint responde alguns minutos depois. **Models** mostra quando está pronto, o endereço, a chave de API, código para chamar, um teste para modelos de chat e imagem, e o log do motor.

## Suas opções do motor

Cole as opções que você ajustou, do jeito que você as guarda:

```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}'
```

Flags soltas, o comando inteiro e uma linha de `docker run` funcionam, com variáveis na frente e valores JSON entre aspas. Você as escolhe e as mantém atualizadas com as versões do seu motor. O Arrakis as lê sem shell e as entrega ao motor palavra por palavra, então:

- Sintaxe de shell (`;`, `|`, `&&`, `$(...)`, `$VARIABLES`) é recusada: nada a executaria.
- Onde o motor escuta (`--host`, `--port`), a chave dele (`--api-key`) e o modelo ficam com o Arrakis, então o endpoint mantém o endereço e a chave. `--served-model-name` (`--alias` no llama.cpp) muda o nome do modelo usado nas requisições.
- Seu paralelismo vale: com `-tp`, `--tp` ou `-dp` nas suas opções, o Arrakis não adiciona o dele.
- Configurações que escolhem GPUs (`NVIDIA_*`) e do carregador (`LD_*`) são recusadas: uma máquina usa as GPUs que aluga.
- Seu token do Hugging Face vai no campo próprio dele, nunca nas opções, para não ser salvo junto com elas.

## Pela 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"}'
```

Sem `node_id`, o Arrakis aluga a máquina mais bem classificada que comporta o modelo, com o menor número de GPUs possível. `POST /v1/deploy/plan` lista antes, de graça, todas as GPUs em que ele cabe, e com `extra_args` confere suas opções e devolve a linha de início. A resposta traz o endpoint e a `api_key` dele; `GET /v1/instances/{id}/endpoint` os devolve de novo, com `ready` quando o modelo responde, e `GET /v1/instances/{id}/endpoint/log` o final do log do motor. Agentes usam a ferramenta `deploy_model` via [MCP](/pt/docs/agents).

## Chame o modelo

O endpoint fala a API da OpenAI, então qualquer cliente da OpenAI funciona. O nome do modelo numa requisição é o ID dele no Hugging Face, sem a quantização, a menos que você o tenha renomeado.

```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)
```

| O modelo gera | Peça em |
|---|---|
| Texto | `POST /v1/chat/completions`, `/v1/completions`, `/v1/embeddings` |
| Imagens | `POST /v1/images/generations`, `/v1/images/edits` |
| Vídeo | `POST /v1/videos`, depois `GET /v1/videos/{id}` até terminar e `GET /v1/videos/{id}/content` |
| Voz | `POST /v1/audio/speech` |
| Som e música | `POST /v1/audio/generate` |
| Texto a partir de fala | `POST /v1/audio/transcriptions` |

## A máquina é sua

- É um aluguel comum: cobrado por hora, removido no horário de remoção e listado em **Instances**.
- Ela inicia com uma imagem Arrakis construída sobre a versão oficial do motor, com SSH como root. Rode nela `arrakis-serve status`, `arrakis-serve logs` ou `arrakis-serve restart`.
- Para testar outras opções sem uma máquina nova, edite `/etc/arrakis/serve/command` (uma palavra por linha) ou `/etc/arrakis/serve/env` e rode `arrakis-serve restart`. Quando o motor para, a máquina continua ligada para você corrigir.
- O endpoint é o endereço da máquina em HTTP simples. Um controle de acesso na porta 8000 confere a chave de API (`Authorization: Bearer <key>`) antes que uma requisição chegue ao motor, que só escuta dentro da máquina; `/health` responde sem a chave e diz apenas se o motor está no ar. Para tráfego privado, abra um túnel SSH (`ssh root@<host> -p <port> -N -L 8000:localhost:8000`) e use `http://localhost:8000/v1`.
- Seu token do Hugging Face vai para a máquina como `HF_TOKEN`, e o Arrakis não o guarda. O host da máquina pode ler o que roda nela, então use um token granular (fine-grained) e só de leitura.

Mais: [toda a documentação](/pt/docs.md) · [OpenAPI](/openapi.json) · [llms.txt](/pt/llms.txt)