> ## Documentation Index
> Fetch the complete documentation index at: https://novita.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Guia do usuário de Deployments da Novita

> **Navegação**: Models Console → Deployments
> **Aplica-se a**: Versão atual em produção
> **Última atualização**: 2026-04-20

***

## Sumário

1. [O que são Deployments](#1-what-are-deployments)
2. [Início rápido (Entre em produção em 5 minutos)](#2-quick-start-go-live-in-5-minutes)
3. [Criando um Deployment](#3-creating-a-deployment)
   * 3.1 [Nomenclatura](#31-naming)
   * 3.2 [Selecionando um modelo](#32-selecting-a-model)
   * 3.3 [Selecionando uma instância de GPU](#33-selecting-a-gpu-instance)
   * 3.4 [Configurando o autoscaling](#34-configuring-autoscaling)
   * 3.5 [Configurações do mecanismo (Avançado)](#35-engine-settings-advanced)
4. [Ciclo de vida e status do Deployment](#4-deployment-lifecycle--status)
5. [Autoscaling em detalhes](#5-autoscaling-in-depth)
6. [Suporte a LoRA Adapter](#6-lora-adapter-support)
7. [Cobrança](#7-billing)
8. [FAQ e solução de problemas](#8-faq--troubleshooting)

***

## 1. O que são Deployments

Um Deployment é o produto de **endpoint dedicado de inferência de IA** da Novita. Diferentemente dos endpoints Serverless, que compartilham recursos de computação com outros usuários, cada Deployment oferece:

* **GPU exclusiva**: Todos os recursos de computação são somente seus — sem vizinhos barulhentos
* **SLA de desempenho previsível**: Computação dedicada significa latência de inferência consistente e previsível
* **Fontes de modelo flexíveis**: Implante qualquer modelo do Hugging Face ou do catálogo de modelos da Novita
* **API de chat compatível com OpenAI**: Para inferência de texto puro, basta trocar `base_url` e `model` para migrar integrações OpenAI existentes
* **Cobrança por segundo**: Você só é cobrado enquanto o endpoint está ativo. A cobrança é pausada automaticamente quando o Scale-to-Zero entra em ação

**Quando usar Deployments:**

| Caso de uso                           | Por que se encaixa                                           |
| ------------------------------------- | ------------------------------------------------------------ |
| Serviços de API em produção           | Latência estável, totalmente isolado de outros usuários      |
| Servir modelos privados ou fine-tuned | Implante qualquer modelo HuggingFace personalizado           |
| Inferência de alta concorrência       | Escale automaticamente para múltiplas réplicas               |
| Workloads sensíveis a custo           | Scale-to-Zero interrompe a cobrança durante períodos ociosos |

***

## 2. Início rápido (Entre em produção em 5 minutos)

**Etapa 1 — Navegue até Deployments**

Faça login na Novita → barra lateral esquerda → **Models Console** → **Models APIs** → **Deployments**

**Etapa 2 — Crie um Deployment**

Clique em **+ New Deployment** e preencha:

* Um nome para o Deployment (por exemplo, `my-llama3-endpoint`)
* Fonte do modelo (o catálogo de modelos da Novita é recomendado para a configuração mais rápida)
* Instância de GPU (o sistema recomenda automaticamente uma especificação adequada para o seu modelo)
* Configurações de autoscaling

**Etapa 3 — Aguarde o Deployment iniciar**

O tempo de inicialização varia conforme o tamanho do modelo, normalmente **5–60 minutos**, passando por três fases:

1. Solicitando GPU
2. Baixando o modelo
3. Inicializando o mecanismo

Quando o status mostrar **RUNNING**, o endpoint estará pronto para receber solicitações.

**Etapa 4 — Chame a API**

Vá para a página de detalhes do Deployment → painel **Quick Start** → copie o snippet de código pronto para execução.

> Gerencie suas API Keys em **Settings → API Keys**.

***

## 3. Criando um Deployment

Clique em **+ New Deployment** para abrir o formulário de criação, que tem quatro seções de configuração.

### 3.1 Nomenclatura

Formato de nomenclatura recomendado: `{model}-{environment}-{purpose}` — por exemplo, `llama3-prod-chatbot`.

### 3.2 Selecionando um modelo

Duas fontes de modelo são compatíveis:

#### Catálogo de modelos da Novita (Recomendado)

Escolha na lista de modelos hospedados da Novita — nenhum token é necessário, **funciona imediatamente**. Abrange todos os principais modelos open-source (Llama 3, Qwen, DeepSeek, Mistral e outros).

> A Novita pré-valida a compatibilidade do modelo e aplica otimizações de mecanismo, resultando em inicialização mais rápida e maior estabilidade.

#### Modelos do Hugging Face

Insira um ID de repositório do HuggingFace (por exemplo, `meta-llama/Meta-Llama-3-8B-Instruct`).

* **Modelos públicos**: Nenhum token é necessário, implante diretamente
* **Modelos privados ou Gated**: Um HuggingFace Access Token deve ser vinculado primeiro

**Como vincular seu HF Token:**

1. Vá para [HuggingFace → Settings → Access Tokens](https://huggingface.co/settings/tokens) e crie um token
2. No campo Model no formulário Create Deployment, clique em **Integrate HF Token**
3. Cole e salve o token

> Se seu token expirar ou for revogado, Deployments ativos que dependem dele falharão ao tentar baixar novamente o modelo. Mantenha seu token atualizado.

#### LoRA Adapter (Opcional)

Depois de selecionar um Base Model, você pode anexar um ou mais LoRA Adapters do HuggingFace. Vários adapters podem ser executados no mesmo Deployment sem exigir recursos adicionais de GPU.

Consulte a [Seção 6 — Suporte a LoRA Adapter](#6-lora-adapter-support) para obter detalhes.

**Requisitos de formato de arquivo do modelo (para modelos HuggingFace personalizados):**

### 3.3 Selecionando uma instância de GPU

O sistema recomenda automaticamente uma configuração de GPU com base no tamanho do seu modelo.

> **Aviso de TIGHT MEMORY**: Se a GPU selecionada tiver VRAM limitada para o modelo escolhido, o sistema mostrará um aviso `TIGHT MEMORY`. Aumente a quantidade de GPUs ou entre em contato com o suporte da Novita.

> O tipo de GPU **não pode ser alterado** depois que um Deployment é criado. Para trocar o tipo de GPU, exclua e recrie o Deployment.

***

### 3.4 Configurando o autoscaling

O autoscaling controla quantas réplicas são executadas em resposta ao tráfego.

#### Habilitar autoscaling (Recomendado)

Use o controle deslizante de duas alças para definir o intervalo de réplicas:

| Parâmetro        | Descrição                                                                                | Padrão        |
| ---------------- | ---------------------------------------------------------------------------------------- | ------------- |
| Min Replicas     | Mínimo de réplicas ativas o tempo todo. Defina como 0 para habilitar Scale-to-Zero       | 1             |
| Max Replicas     | Máximo de réplicas durante picos de tráfego                                              | 3             |
| Scale-down Delay | Segundos de espera depois que o tráfego cai antes de reduzir a escala (previne flapping) | 300s (mínimo) |

**Scale-to-Zero (Min Replicas = 0):**

* Depois de ficar ocioso por mais tempo que o Scale-down Delay, o Deployment entra no status **SLEEPING** e a cobrança é pausada
* A primeira solicitação recebida o ativa automaticamente
* Tempo de cold start: geralmente 5 minutos, dependendo do tamanho do modelo
* ⚠️ Mais adequado para workloads de desenvolvimento/test ou de baixa frequência. Para produção, mantenha Min Replicas ≥ 1

#### Desabilitar autoscaling

Executa um número fixo de réplicas. Melhor para workloads com SLAs de latência rigorosos que não toleram nenhum atraso de escalonamento.

### 3.5 Configurações do mecanismo (Avançado)

A Novita oferece suporte a dois mecanismos de inferência — **vLLM** e **SGLang** — correspondidos automaticamente ao seu modelo. Essas configurações ficam ocultas por padrão durante a criação do Deployment.

#### Max Concurrency por réplica

Controla quantas solicitações uma única réplica processa simultaneamente.

| Configuração          | Efeito                                                     |
| --------------------- | ---------------------------------------------------------- |
| Abaixo do recomendado | Menor latência, mas throughput limitado                    |
| Igual ao recomendado  | Equilíbrio ideal entre throughput e latência (recomendado) |
| Acima do recomendado  | Maior throughput, mas aumento da latência por solicitação  |

> O sistema calcula um valor recomendado com base na sua instância de GPU. O padrão é 16.

#### Suffix Decoding

Decodificação especulativa baseada em N-gram que pré-gera tokens futuros para acelerar a inferência.

* Mais eficaz para **formatos de saída altamente previsíveis** (por exemplo, geração de código, JSON estruturado)
* Oferece benefício limitado para conversas em formato livre; valores excessivamente altos podem, na verdade, aumentar a latência

***

## 4. Ciclo de vida e status do Deployment

### Diagrama de transição de estado

```text theme={"system"}
Create
  │
  ▼
PENDING ──── Waiting for GPU resource allocation
  │
  ▼
DEPLOYING ── Three sub-phases:
  │            ├─ Requesting GPU
  │            ├─ Downloading Model
  │            └─ Engine Initializing
  │
  ├──────────────── FAILED (deployment failed)
  │
  ▼
RUNNING ──── Live and accepting requests
  │
  ├─ Zero traffic + Scale-to-Zero enabled ──► SLEEPING
  │                                               │
  │                                 First request ──► DEPLOYING ──► RUNNING
  │
  ├─ Config update ──► ROLLING (zero-downtime rolling update)
  │
  ├─ Traffic change ──► SCALING (autoscaling in progress)
  │
  └─ Manual terminate ──► TERMINATING ──► TERMINATED (can be redeployed or deleted)
```

> **Quando a cobrança começa**: Somente réplicas em execução são cobradas. Instâncias ainda em implantação e réplicas ainda aumentando a escala não contam para as cobranças.

***

## 5. Autoscaling em detalhes

### Como funciona

O autoscaling da Novita monitora o tráfego em tempo real e ajusta dinamicamente a quantidade de réplicas dentro do intervalo Min–Max:

* **Scale-Up**: Acúmulo na fila de solicitações detectado → adiciona réplicas → mais GPUs processam solicitações em paralelo
* **Scale-Down**: O tráfego cai → aguarda o Scale-down Delay expirar → reduz réplicas
* **Scale-to-Zero**: Quando Min Replicas = 0 e o Deployment fica ocioso além do atraso, ele entra em SLEEPING e a cobrança para

### Compromisso entre custo e disponibilidade

| Configuração        | Custo                              | Disponibilidade                       | Melhor para                                               |
| ------------------- | ---------------------------------- | ------------------------------------- | --------------------------------------------------------- |
| Min=0, Max=N        | Menor (sem cobrança quando ocioso) | Atraso de cold start (5 min)          | Workloads de desenvolvimento/test, ou de baixa frequência |
| Min=1, Max=N        | Médio                              | Sempre disponível, escala sob demanda | A maioria dos workloads de produção ✅                     |
| Min=N, Max=N (fixo) | Maior                              | Nenhum atraso de escalonamento        | Requisitos de SLA de latência ultrabaixa                  |

### Custo por réplica

Cada réplica adicional adiciona custo na mesma taxa de GPU da réplica base.
Exemplo: um Deployment 2× H100 que escala para 2 réplicas dobra o custo de GPU.

### Melhores práticas

* Defina **Min Replicas = 1** em produção para evitar que cold starts impactem usuários finais
* O Scale-down Delay padrão de 300s (5 minutos) funciona bem para a maioria dos casos; aumente-o se seu tráfego for altamente variável
* Defina Max Replicas como no máximo 1,5× o seu esperado (QPS de pico / QPS por réplica) para evitar picos de custo inesperados

***

## 6. Suporte a LoRA Adapter

### O que é LoRA

LoRA (Low-Rank Adaptation) é uma técnica de fine-tuning eficiente em parâmetros que adiciona camadas leves de adapter sobre um Base Model para personalizá-lo para tarefas específicas — sem retreinar o modelo completo.

### Usando LoRA em Novita Deployments

**Adicionando adapters no momento da criação:**

Em Create Deployment → campo Model → depois de selecionar um Base Model, clique em **+ Add Adapter** e insira o ID do repositório HuggingFace do LoRA adapter.

**Visualizando adapters em runtime:**

No painel Engine Configuration, um badge `+N LoRA` aparece ao lado do Model ID. Passe o cursor sobre ele para ver a lista completa de adapters anexados.

### Multi-LoRA: vários adapters em um Deployment

Um único Deployment pode executar vários LoRA adapters simultaneamente. Especifique qual adapter usar por solicitação por meio do campo `model`:

> Multi-LoRA não exige recursos extras de GPU. Todos os adapters compartilham uma única cópia dos pesos do Base Model na memória.

***

## 7. Cobrança

### Unidade de cobrança

Cobrado por **GPU-segundo**: número de GPUs × segundos em execução × preço unitário.

### Quando a cobrança começa e termina

| Evento                 | Detalhes                                                                                              |
| ---------------------- | ----------------------------------------------------------------------------------------------------- |
| **A cobrança começa**  | Depois que a alocação de GPU é concluída durante DEPLOYING (ou seja, quando Downloading Model começa) |
| **A cobrança termina** | Quando o Deployment entra no status SLEEPING ou TERMINATED                                            |
| **Cobrança contínua**  | Um Deployment em RUNNING é cobrado mesmo quando recebe zero solicitações de API                       |

### Preços de GPU

> Para os preços mais recentes, consulte a [página de preços da Novita](https://novita.ai/pricing).

### Exemplo de cobrança

**Cenário**: Um cliente implanta a instância de modelo X em uma única RTX 4090 (com preço de \$0.61/GPU/hour), com autoscaling definido como Min=0, Max=5.

Uso e cobranças para 9:00–10:00:

1. **9:00:00 – 9:15:40** — A instância está em SLEEPING. Cobrança: **\$0.00**
2. **9:15:41 – 9:16:45** — 1 réplica em execução servindo tráfego (65 segundos).
   Cobrança: ($0.61 ÷ 3600) × 1 réplica × 65s = **$0.011\*\*
3. **9:16:46 – 10:00:00** — 2 réplicas em execução servindo tráfego (1.994 segundos).
   Cobrança: ($0.61 ÷ 3600) × 2 réplicas × 1.994s = **$0.676\*\*

**Total de 9:00–10:00: $0 + $0.011 + $0.676 = $0.687**

### Dicas de controle de custos

1. **Habilite Scale-to-Zero** (Min Replicas = 0) para workloads de baixa frequência — custo zero quando ocioso
2. **Audite sua lista de Deployments regularmente** e exclua Deployments não utilizados
3. **Limite Max Replicas de forma conservadora** para evitar picos de custo inesperados causados por autoscaling descontrolado
4. **O status TERMINATED não custa nada** — termine e reimplante sob demanda

***

## 8. FAQ e solução de problemas

### Problemas de Deployment

**P: Meu Deployment ficou preso em DEPLOYING por muito tempo — o que devo fazer?**

* `Requesting GPU`: Os recursos de GPU podem estar restritos. Aguarde 5–10 minutos ou tente um tipo de GPU diferente
* `Downloading Model`: Modelos grandes (70B+) podem levar mais de 10 minutos para baixar
* `Engine Initializing`: Deve ser concluído em até 5 minutos em condições normais

**P: Meu Deployment mostra FAILED — quais são as causas comuns?**

* O modelo não está no formato `.safetensors` (`.bin` não é compatível)
* O HuggingFace Token é inválido ou não tem acesso a um modelo gated
* VRAM de GPU insuficiente para o modelo (configuração TIGHT MEMORY)
* A arquitetura do modelo ainda não é compatível

Etapas de depuração: verifique o log de alterações na aba Settings → verifique o formato do arquivo do modelo → valide o HF Token → aumente a quantidade de GPUs e recrie o Deployment.

**P: Meu Deployment está em SLEEPING — como faço para ativá-lo?**

Envie qualquer solicitação de API para ele. O Deployment acorda automaticamente. A primeira solicitação aguarda a conclusão do cold start antes de receber uma resposta.

***

### Problemas de API

**P: O que significam os códigos de erro HTTP comuns?**

| Código | Causa                                                               | Resolução                                                                                      |
| ------ | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| `400`  | Solicitação malformada                                              | Valide o JSON da solicitação; garanta que todos os campos obrigatórios estejam presentes       |
| `401`  | API Key ausente ou inválida                                         | Inclua uma chave válida em `Authorization: Bearer <Key>`                                       |
| `403`  | A API Key não tem acesso a este endpoint                            | Confirme que a chave pertence à mesma conta proprietária do Deployment                         |
| `404`  | Endpoint URL ou Model ID incorreto                                  | Copie novamente a URL e o Model ID do painel Quick Start                                       |
| `422`  | Valor de parâmetro inválido (por exemplo, max\_tokens muito grande) | Ajuste o parâmetro — tente reduzir max\_tokens                                                 |
| `429`  | Limite de taxa excedido                                             | Reduza a frequência das solicitações ou entre em contato com a Novita para aumentar seu limite |
| `500`  | Erro interno do servidor                                            | Tente novamente após uma breve espera; se persistir, entre em contato com o suporte da Novita  |

**P: Onde encontro minha API Key?**

Vá para **Settings → API Keys** para criar ou gerenciar chaves. Uma chave é exibida apenas uma vez na criação — salve-a imediatamente.

***

### Problemas de cobrança

**P: Por que estou sendo cobrado quando não há solicitações?**

Um Deployment em RUNNING ocupa continuamente recursos de GPU, independentemente do volume de solicitações.
**Correção**: Habilite Autoscaling e defina Min Replicas = 0. O Deployment entrará automaticamente em sleep e interromperá a cobrança quando estiver ocioso.

**P: Como interrompo completamente todas as cobranças?**

Duas opções:

* **Scale-to-Zero**: Deixe o autoscaling acionar naturalmente (exige Autoscaling ativado com Min = 0)
* **Terminate**: Clique em **Terminate** na página de detalhes do Deployment para liberar a GPU imediatamente

***

## Apêndice: Glossário

| Termo            | Definição                                                                                            |
| ---------------- | ---------------------------------------------------------------------------------------------------- |
| Deployment       | Produto de endpoint dedicado de inferência da Novita                                                 |
| Replica          | Uma única instância em execução do serviço de inferência; várias réplicas são executadas em paralelo |
| Scale-to-Zero    | Configurar Min Replicas como 0 para que o endpoint entre em sleep quando ocioso e a cobrança pare    |
| Scale-down Delay | Período de espera antes de reduzir a escala, prevenindo flapping em tráfego variável                 |
| LoRA Adapter     | Plugin leve de fine-tuning em camadas sobre um Base Model                                            |
| Endpoint URL     | O endereço de acesso da API para este Deployment                                                     |
| Endpoint ID      | Identificador exclusivo deste Deployment                                                             |
| Base Model       | O modelo de base subjacente que está sendo servido                                                   |
| Max Concurrency  | Máximo de solicitações simultâneas que uma única réplica processa                                    |
| Suffix Decoding  | Decodificação especulativa N-gram para acelerar a inferência em saídas previsíveis                   |
| GPU-second       | Unidade de cobrança: 1 GPU em execução por 1 segundo                                                 |

***

*Para suporte, entre em contato com a equipe da Novita em: [support@novita.ai](mailto:support@novita.ai)*