> ## 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.

# Novita Deployments ユーザーガイド

> **ナビゲーション**: Models Console → Deployments
> **対象**: 現行の本番バージョン
> **最終更新日**: 2026-04-20

***

## 目次

1. [Deployments とは](#1-what-are-deployments)
2. [クイックスタート（5 分で本番稼働）](#2-quick-start-go-live-in-5-minutes)
3. [Deployment の作成](#3-creating-a-deployment)
   * 3.1 [命名](#31-naming)
   * 3.2 [モデルの選択](#32-selecting-a-model)
   * 3.3 [GPU インスタンスの選択](#33-selecting-a-gpu-instance)
   * 3.4 [Autoscaling の設定](#34-configuring-autoscaling)
   * 3.5 [Engine Settings（詳細設定）](#35-engine-settings-advanced)
4. [Deployment のライフサイクルとステータス](#4-deployment-lifecycle--status)
5. [Autoscaling の詳細](#5-autoscaling-in-depth)
6. [LoRA Adapter のサポート](#6-lora-adapter-support)
7. [課金](#7-billing)
8. [FAQ とトラブルシューティング](#8-faq--troubleshooting)

***

## 1. Deployments とは

Deployment は、Novita の **専用 AI 推論エンドポイント**製品です。他のユーザーとコンピューティングリソースを共有する Serverless エンドポイントとは異なり、各 Deployment では次のものが提供されます。

* **専有 GPU**: すべてのコンピューティングリソースを自分だけで利用できます — ノイジーネイバーはありません
* **予測可能なパフォーマンス SLA**: 専用コンピューティングにより、一貫性があり予測しやすい推論レイテンシを実現します
* **柔軟なモデルソース**: Hugging Face または Novita モデルカタログの任意のモデルをデプロイできます
* **OpenAI 互換 Chat API**: 純粋なテキスト推論では、既存の OpenAI 連携を移行するために `base_url` と `model` を差し替えるだけです
* **秒単位の課金**: エンドポイントがアクティブな間のみ課金されます。Scale-to-Zero が作動すると、課金は自動的に一時停止します

**Deployments を使用する場面:**

| ユースケース                         | 適している理由                         |
| ------------------------------ | ------------------------------- |
| 本番 API サービス                    | 安定したレイテンシ、他のユーザーから完全に分離         |
| プライベートモデルまたはファインチューニング済みモデルの提供 | 任意のカスタム HuggingFace モデルをデプロイ可能  |
| 高同時実行の推論                       | 複数のレプリカへ自動的にスケール                |
| コスト重視のワークロード                   | アイドル期間中は Scale-to-Zero により課金を停止 |

***

## 2. クイックスタート（5 分で本番稼働）

**ステップ 1 — Deployments に移動する**

Novita にログイン → 左サイドバー → **Models Console** → **Models APIs** → **Deployments**

**ステップ 2 — Deployment を作成する**

**+ New Deployment** をクリックし、次を入力します。

* Deployment 名（例: `my-llama3-endpoint`）
* モデルソース（最短でセットアップするには Novita モデルカタログを推奨）
* GPU インスタンス（システムがモデルに適した仕様を自動推奨）
* Autoscaling 設定

**ステップ 3 — Deployment の起動を待つ**

起動時間はモデルサイズによって異なりますが、通常は **5〜60 分**です。次の 3 フェーズで進行します。

1. GPU のリクエスト
2. モデルのダウンロード
3. エンジンの初期化

ステータスが **RUNNING** と表示されたら、エンドポイントはリクエストを受信する準備ができています。

**ステップ 4 — API を呼び出す**

Deployment 詳細ページ → **Quick Start** パネルに移動し、そのまま実行できるコードスニペットをコピーします。

> API Keys は **Settings → API Keys** で管理します。

***

## 3. Deployment の作成

**+ New Deployment** をクリックして作成フォームを開きます。フォームには 4 つの設定セクションがあります。

### 3.1 命名

推奨される命名形式: `{model}-{environment}-{purpose}` — 例: `llama3-prod-chatbot`。

### 3.2 モデルの選択

2 つのモデルソースがサポートされています。

#### Novita Model Catalog（推奨）

Novita がホストするモデル一覧から選択します — トークンは不要で、**すぐに動作します**。主要なオープンソースモデル（Llama 3、Qwen、DeepSeek、Mistral など）を網羅しています。

> Novita はモデル互換性を事前検証し、エンジン最適化を適用するため、起動が速くなり安定性も高まります。

#### Hugging Face Models

HuggingFace リポジトリ ID（例: `meta-llama/Meta-Llama-3-8B-Instruct`）を入力します。

* **公開モデル**: トークン不要で直接デプロイ可能
* **Private または Gated モデル**: HuggingFace Access Token を先にリンクする必要があります

**HF Token をリンクする方法:**

1. [HuggingFace → Settings → Access Tokens](https://huggingface.co/settings/tokens) に移動し、トークンを作成します
2. Create Deployment フォームの Model フィールドで **Integrate HF Token** をクリックします
3. トークンを貼り付けて保存します

> トークンの有効期限が切れたり取り消されたりすると、そのトークンに依存するアクティブな Deployments はモデルの再取得に失敗します。トークンは最新の状態に保ってください。

#### LoRA Adapter（任意）

Base Model を選択した後、HuggingFace から 1 つ以上の LoRA Adapters をアタッチできます。複数のアダプターを、追加の GPU リソースなしで同じ Deployment 上で実行できます。

詳細は [セクション 6 — LoRA Adapter のサポート](#6-lora-adapter-support) を参照してください。

**モデルファイル形式の要件（カスタム HuggingFace モデル向け）:**

### 3.3 GPU インスタンスの選択

システムは、モデルサイズに基づいて GPU 構成を自動的に推奨します。

> **TIGHT MEMORY 警告**: 選択した GPU の VRAM が選択モデルに対して限られている場合、システムは `TIGHT MEMORY` 警告を表示します。GPU 数を増やすか、Novita サポートにお問い合わせください。

> Deployment 作成後に GPU タイプを変更することは**できません**。GPU タイプを切り替えるには、Deployment を削除して再作成してください。

***

### 3.4 Autoscaling の設定

Autoscaling は、トラフィックに応じて実行されるレプリカ数を制御します。

#### Autoscaling を有効にする（推奨）

デュアルハンドルスライダーを使用して、レプリカ範囲を設定します。

| パラメータ            | 説明                                              | デフォルト    |
| ---------------- | ----------------------------------------------- | -------- |
| Min Replicas     | 常時アクティブな最小レプリカ数。Scale-to-Zero を有効にするには 0 に設定します | 1        |
| Max Replicas     | ピークトラフィック時の最大レプリカ数                              | 3        |
| Scale-down Delay | トラフィック低下後、スケールダウンするまで待機する秒数（フラッピングを防止）          | 300s（最小） |

**Scale-to-Zero（Min Replicas = 0）:**

* Scale-down Delay を超えてアイドル状態が続くと、Deployment は **SLEEPING** ステータスになり、課金が一時停止します
* 最初の受信リクエストで自動的に起動します
* コールドスタート時間: モデルサイズによりますが通常は 5 分
* ⚠️ 開発/test または低頻度ワークロードに最適です。本番環境では Min Replicas ≥ 1 を維持してください

#### Autoscaling を無効にする

固定数のレプリカを実行します。スケーリング遅延を一切許容できない、厳格なレイテンシ SLA を持つワークロードに最適です。

### 3.5 Engine Settings（詳細設定）

Novita は **vLLM** と **SGLang** の 2 つの推論エンジンをサポートしており、モデルに合わせて自動的に選択されます。これらの設定は、Deployment 作成時にはデフォルトで非表示になっています。

#### Max Concurrency per Replica

単一レプリカが同時に処理するリクエスト数を制御します。

| 設定      | 効果                            |
| ------- | ----------------------------- |
| 推奨値未満   | レイテンシは低いが、スループットが制限される        |
| 推奨値と同じ  | スループットとレイテンシの最適なバランス（推奨）      |
| 推奨値を超える | スループットは高いが、リクエストごとのレイテンシが増加する |

> システムは GPU インスタンスに基づいて推奨値を計算します。デフォルトは 16 です。

#### Suffix Decoding

N-gram ベースの投機的デコーディングで、将来のトークンを事前生成して推論を高速化します。

* **予測しやすい出力形式**（例: コード生成、構造化 JSON）で最も効果的です
* 自由形式の会話では効果が限定的です。値を過度に高くすると、かえってレイテンシが増加する場合があります

***

## 4. Deployment のライフサイクルとステータス

### 状態遷移図

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

> **課金が開始されるタイミング**: 実行中のレプリカのみ課金対象です。デプロイ中のインスタンス、およびスケールアップ中のレプリカは料金に含まれません。

***

## 5. Autoscaling の詳細

### 仕組み

Novita autoscaling はライブトラフィックを監視し、Min–Max 範囲内でレプリカ数を動的に調整します。

* **Scale-Up**: リクエストキューのバックログを検出 → レプリカを追加 → より多くの GPU が並列にリクエストを処理
* **Scale-Down**: トラフィックが低下 → Scale-down Delay の経過を待機 → レプリカを削減
* **Scale-to-Zero**: Min Replicas = 0 で、Deployment が遅延時間を超えてアイドル状態になると、SLEEPING になり課金が停止します

### コストと可用性のトレードオフ

| 構成               | コスト            | 可用性                | 最適な用途              |
| ---------------- | -------------- | ------------------ | ------------------ |
| Min=0, Max=N     | 最低（アイドル時は課金なし） | コールドスタート遅延（5 分）    | 開発/test, 低頻度ワークロード |
| Min=1, Max=N     | 中程度            | 常に利用可能、オンデマンドでスケール | ほとんどの本番ワークロード ✅    |
| Min=N, Max=N（固定） | 最高             | スケーリング遅延がまったくない    | 超低レイテンシ SLA 要件     |

### レプリカ単位のコスト

追加レプリカごとに、ベースレプリカと同じ GPU レートでコストが追加されます。
例: 2× H100 Deployment が 2 レプリカにスケールすると、GPU コストは 2 倍になります。

### ベストプラクティス

* エンドユーザーにコールドスタートの影響が出ないよう、本番環境では **Min Replicas = 1** に設定します
* デフォルトの Scale-down Delay である 300s（5 分）は、ほとんどのケースで適切に機能します。トラフィック変動が非常に大きい場合は増やしてください
* 予期しないコスト急増を避けるため、Max Replicas は想定値（ピーク QPS / レプリカごとの QPS）の 1.5 倍以下に設定します

***

## 6. LoRA Adapter のサポート

### LoRA とは

LoRA（Low-Rank Adaptation）は、Base Model の上に軽量なアダプターレイヤーを追加して特定タスク向けにカスタマイズする、パラメータ効率の高いファインチューニング手法です。フルモデルを再トレーニングする必要はありません。

### Novita Deployments で LoRA を使用する

**作成時にアダプターを追加する:**

Create Deployment → Model フィールドで、Base Model を選択した後、**+ Add Adapter** をクリックし、LoRA アダプターの HuggingFace リポジトリ ID を入力します。

**実行時にアダプターを表示する:**

Engine Configuration パネルでは、Model ID の横に `+N LoRA` バッジが表示されます。ホバーすると、アタッチされているアダプターの完全な一覧を確認できます。

### Multi-LoRA: 1 つの Deployment 上の複数アダプター

単一の Deployment で複数の LoRA アダプターを同時に実行できます。リクエストごとに使用するアダプターは、`model` フィールドで指定します。

> Multi-LoRA に追加の GPU リソースは不要です。すべてのアダプターは、メモリ内の Base Model 重みの単一コピーを共有します。

***

## 7. 課金

### 課金単位

**GPU-second** 単位で課金されます: GPU 数 × 実行秒数 × 単価。

### 課金が開始・停止されるタイミング

| イベント     | 詳細                                                         |
| -------- | ---------------------------------------------------------- |
| **課金開始** | DEPLOYING 中に GPU 割り当てが完了した後（つまり Downloading Model が始まった時点） |
| **課金停止** | Deployment が SLEEPING または TERMINATED ステータスになったとき           |
| **継続課金** | RUNNING の Deployment は、API リクエストを 1 件も受信していない場合でも課金されます    |

### GPU 料金

> 最新の料金については、[Novita pricing page](https://novita.ai/pricing) を参照してください。

### 課金例

**シナリオ**: 顧客が単一の RTX 4090（料金 \$0.61/GPU/hour）上にモデルインスタンス X をデプロイし、autoscaling を Min=0、Max=5 に設定しています。

9:00–10:00 の使用量と料金:

1. **9:00:00 – 9:15:40** — インスタンスは SLEEPING。料金: **\$0.00**
2. **9:15:41 – 9:16:45** — 1 つの実行中レプリカがトラフィックを処理（65 秒）。
   料金: ($0.61 ÷ 3600) × 1 replica × 65s = **$0.011\*\*
3. **9:16:46 – 10:00:00** — 2 つの実行中レプリカがトラフィックを処理（1,994 秒）。
   料金: ($0.61 ÷ 3600) × 2 replicas × 1,994s = **$0.676\*\*

**9:00–10:00 の合計: $0 + $0.011 + $0.676 = $0.687**

### コスト管理のヒント

1. 低頻度ワークロードでは **Scale-to-Zero**（Min Replicas = 0）を有効にします — アイドル時のコストはゼロです
2. **Deployment 一覧を定期的に監査**し、未使用の Deployments を削除します
3. runaway autoscaling による予期しないコスト急増を防ぐため、**Max Replicas を保守的に上限設定**します
4. **TERMINATED ステータスではコストは発生しません** — 必要に応じて終了し、再デプロイしてください

***

## 8. FAQ とトラブルシューティング

### Deployment の問題

**Q: Deployment が長時間 DEPLOYING のままです — どうすればよいですか？**

* `Requesting GPU`: GPU リソースが逼迫している可能性があります。5〜10 分待つか、別の GPU タイプを試してください
* `Downloading Model`: 大規模モデル（70B+）はダウンロードに 10 分以上かかることがあります
* `Engine Initializing`: 通常条件では 5 分以内に完了するはずです

**Q: Deployment が FAILED と表示されます — 一般的な原因は何ですか？**

* モデルが `.safetensors` 形式ではない（`.bin` はサポートされていません）
* HuggingFace Token が無効、または gated model へのアクセス権がない
* モデルに対して GPU VRAM が不足している（TIGHT MEMORY 構成）
* モデルアーキテクチャがまだサポートされていない

デバッグ手順: Settings Tab の変更ログを確認 → モデルファイル形式を確認 → HF Token を検証 → GPU 数を増やして Deployment を再作成します。

**Q: Deployment が SLEEPING です — どうやって起動しますか？**

任意の API リクエストを送信してください。Deployment は自動的に起動します。最初のリクエストは、レスポンスを受け取る前にコールドスタートの完了を待ちます。

***

### API の問題

**Q: 一般的な HTTP エラーコードは何を意味しますか？**

| Code  | 原因                               | 解決策                                             |
| ----- | -------------------------------- | ----------------------------------------------- |
| `400` | 不正な形式のリクエスト                      | リクエスト JSON を検証し、必須フィールドがすべて存在することを確認してください      |
| `401` | API Key がない、または無効                | 有効なキーを `Authorization: Bearer <Key>` に含めてください   |
| `403` | API Key にこのエンドポイントへのアクセス権がない     | キーが Deployment を所有する同じアカウントに属していることを確認してください    |
| `404` | Endpoint URL または Model ID が誤っている | Quick Start パネルから URL と Model ID を再コピーしてください    |
| `422` | パラメータ値が無効（例: max\_tokens が大きすぎる） | パラメータを調整してください — max\_tokens を減らしてみてください        |
| `429` | レート制限を超過                         | リクエスト頻度を下げるか、上限引き上げについて Novita にお問い合わせください      |
| `500` | 内部サーバーエラー                        | 少し待ってから再試行してください。継続する場合は Novita サポートにお問い合わせください |

**Q: API Key はどこで確認できますか？**

キーを作成または管理するには **Settings → API Keys** に移動します。キーは作成時に一度だけ表示されます — すぐに保存してください。

***

### 課金の問題

**Q: リクエストがないのに課金されるのはなぜですか？**

RUNNING の Deployment は、リクエスト量に関係なく GPU リソースを継続的に占有します。
**修正方法**: Autoscaling を有効にし、Min Replicas = 0 に設定します。Deployment はアイドル時に自動的にスリープし、課金を停止します。

**Q: すべての料金を完全に停止するにはどうすればよいですか？**

2 つの選択肢があります。

* **Scale-to-Zero**: Autoscaling に自然にトリガーさせます（Autoscaling がオンで Min = 0 である必要があります）
* **Terminate**: Deployment 詳細ページで **Terminate** をクリックし、GPU を即時解放します

***

## 付録: 用語集

| 用語               | 定義                                                   |
| ---------------- | ---------------------------------------------------- |
| Deployment       | Novita の専用推論エンドポイント製品                                |
| Replica          | 推論サービスの単一の実行中インスタンス。複数のレプリカは並列に実行されます                |
| Scale-to-Zero    | Min Replicas を 0 に設定し、アイドル時にエンドポイントをスリープさせて課金を停止すること |
| Scale-down Delay | スケールダウン前の待機時間。変動するトラフィックでのフラッピングを防止します               |
| LoRA Adapter     | Base Model の上に重ねる軽量なファインチューニングプラグイン                  |
| Endpoint URL     | この Deployment の API アクセスアドレス                         |
| Endpoint ID      | この Deployment の一意の識別子                                |
| Base Model       | 提供されている基盤モデル                                         |
| Max Concurrency  | 単一レプリカが処理する最大同時リクエスト数                                |
| Suffix Decoding  | 予測可能な出力で推論を高速化する N-gram 投機的デコーディング                   |
| GPU-second       | 課金単位: 1 GPU が 1 秒間実行されること                            |

***

*サポートが必要な場合は、Novita チームまでお問い合わせください: [support@novita.ai](mailto:support@novita.ai)*