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

> ## Agent Instructions
> Tokios exposes private local models through https://api.tokios.com using an outbound-only connector tunnel.
> Use 'connector' for the local tokios-connector process.
> Use 'deployment' for the public model name in the API model field.
> Use 'upstream model id' for the model served by Ollama, llama.cpp, vLLM, LM Studio, or another local backend.
> API keys use the prefix sk-tok-. Connector tokens use the prefix ct-tok-.

# SGLang の設定と使いどころ

> RAG やエージェントのワークロード向けに SGLang を設定します。プレフィックスキャッシュのための RadixAttention、vLLM と SGLang の選択マトリクス、SGLang 固有の最適化フラグを解説します。

SGLangはスループット向けに構築された高性能サービングランタイムである。その特徴であるRadixAttentionは、共有トークンプレフィックスを持つリクエスト間で計算を再利用するツリー構造化されたKVキャッシュを使用する。これにより、多くのリクエストが同じシステムプロンプト、ツールスキーマ、または取得済みコンテキストを持つワークロード — RAGパイプライン、マルチターンチャット、エージェントループ — において、SGLangは最強のオープンソース選択肢となる。

このガイドでは、vLLMよりもSGLangを選ぶべき時期、重要な設定フラグ、および一般的なセットアップ向けのすぐに使える起動コマンドを解説する。

> [!NOTE]
>
> Last verified: 2026-10-14. This page reflects SGLang **v0.5.21** (released October 2, 2026). Flag names and defaults can shift between releases — verify against your installed version with `python -m sglang.launch_server --help`.

## RadixAttention

SGLangのKVキャッシュはフラットなテーブルではなく、トークンシーケンスをキーとする**ラジックスリー**である。どのリクエストがこれまで処理したプレフィックスもすべてツリー内に保持される。新しいリクエストが到着すると、SGLangはツリーを走査して最長一致のプレフィックスを見つけ、再計算せずにキャッシュされたKV状態を再利用する。

具体的に、10件のリクエストが2,000トークンのシステムプロンプトを共有する場合、プロンプトは一度だけプリフィルされる。残りの9件のリクエストはデコードに直接進む。会話が発散すると、各ブランチは独自のキャッシュノードを取得し、任意の深さで共有プレフィックスが独立して再利用される。

パフォーマンスの違いはプレフィックス重視のワークロードで顕著である。50件の同時リクエストで80%の共有プレフィックスの場合、SGLangはvLLMと比較して**37%低いTTFT**を実現する。この優位性はプレフィックスの重複が増えるほど拡大し、すべてのリクエストがユニークな場合は縮小する。

> [!TIP]
>
> RadixAttentionは有効化するものではなく、SGLangのKVキャッシュの動作方式である。すべてのリクエストが自動的に恩恵を受ける。設定フラグは削除ポリシー、メモリ制限、Rustバックエンドのストレージを制御する。

## SGLangが適するケース

ワークロードに**高いプレフィックス重複**がある場合はSGLangを選ぶ：

* **RAGパイプライン** — 同じシステムプロンプトと取得チャンクが多くのクエリにわたって出現する。RadixAttentionはプロンプト + ドキュメントプレフィックスを一度キャッシュし、すべての質問で再利用する。
* **マルチターン会話** — 各ターンは前のコンテキストを拡張する。最後のターンまでの会話履歴全体が共有プレフィックスとなる。
* **ツールスキーマ付きエージェントループ** — エージェントは呼び出しごとに同じツール定義、フューショット例、オーケストレーションプロンプトを送信する。SGLangはそれらのプレフィックスをキャッシュし、新しいツール結果のみをプリフィルする。
* **長い共有システムプロンプト** — 数十または数百のユーザーが大きなシステムプロンプトを共有するデプロイメント（カスタマーサポートボット、コーディングアシスタント、ドキュメントQ\&A）。
* **バッチ評価** — 同じプロンプトテンプレートを異なる変数置換で実行する。テンプレートプレフィックスがキャッシュされ、入力部分のみがプリフィルされる。

## vLLMが適するケース

ワークロードが**広範性**を重視する場合はvLLMを選ぶ：

* **リクエストごとにユニークなプロンプト** — すべてのリクエストが共有プレフィックスなしの完全に異なるプロンプトを持つ場合、RadixAttentionは再利用できない。vLLMのPagedAttentionは独立したリクエストを同等に高速に処理する。
* **幅広いモデルサポート** — vLLMは新しいモデルアーキテクチャのサポートをより速く追加する。先週リリースされたモデルが必要な場合、vLLMが最初にサポートする可能性が高い。
* **Blackwell GPU最適化** — vLLMにはNVIDIA Blackwell（B100/B200/GB200）ハードウェア向けの専用最適化パスがある。Blackwellにデプロイする場合、vLLMがより多くのスループットを引き出す。
* **EAGLE3投機的デコード** — vLLMのEAGLE統合はより成熟している。投機的デコードが主要なレイテンシーレバーの場合、vLLMがより安全な選択肢である。
* **プロダクション硬化** — vLLMはより大きなデプロイベースとプロダクションサービングでの長い実績を持つ。安定性とコミュニティサポートがプレフィックスキャッシュより重要な場合、vLLMがデフォルトである。

## 設定フラグ

主なSGLang固有フラグ（`python -m sglang.launch_server`）は次の通りです：

| フラグ | デフォルト | 用途 |
| - | - | - |
| `--model-path` | （必須） | HuggingFaceリポジトリIDまたはモデルへのローカルパス |
| `--port` | `30000` | OpenAI互換サーバーのリスンポート |
| `--host` | `127.0.0.1` | バインドアドレス — リバースプロキシがSGLangの前にない限りループバックを維持 |
| `--tp` | `1` | GPU間のテンソル並列化 |
| `--mem-fraction-static` | `0.88` | 起動時にKVキャッシュに割り当てられるGPUメモリの割合。余裕がある場合は長コンテキストワークロード向けに`0.90`-`0.92`に増加。 |
| `--context-length` | モデル最大値 | モデルの最大コンテキスト長を上書き。リクエストあたりのKVキャッシュメモリを減らすためにモデル最大値より低く設定。 |
| `--chunked-prefill-size` | `-1`（自動） | 大きなプリフィルをチャンクに分割してデコードのストールを回避。長い入力を持つ混合ワークロードには`2048`-`4096`に設定。 |
| `--disable-radix-cache` | `false` | RadixAttentionを完全に無効化。ほぼ必要ない — SGLangの核心的優位性を削除する。 |
| `--enable-metrics` | `false` | Prometheusメトリクスを`/metrics`で公開します。プロダクションで有効化してください。 |
| `--api-key` | （なし） | SGLangサーバー自体へのリクエストにベアラートークンを要求。ループバックでの多層防御として有用。 |

### Rustバックエンドのプレフィックスキャッシュ

RadixAttentionキャッシュバックエンドは、**v0.5.21**からRustで実装され、デフォルトで有効化されています。Rustバックエンドは以前のPython実装を置き換え、キャッシュルックアップ、挿入、削除のオーバーヘッドを低減します。有効化にフラグは不要です — デフォルトのパスです。

問題が発生した場合は、`--disable-cuda-graph`でPython実装にフォールバックし、使用バージョンの正確なロールバックフラグについてSGLangリリースノートを確認できる。実際には、Rustバックエンドは安定しており高速である。

## 判断マトリクス

| ワークロード | 推奨ランタイム | 理由 |
| - | - | - |
| 繰り返しコンテキスト付きRAG | **SGLang** | RadixAttentionがシステムプロンプト + 取得チャンクをキャッシュ |
| マルチターンチャット（10+ターン） | **SGLang** | 各ターンが共有プレフィックスを拡張 |
| ツールスキーマ付きエージェントループ | **SGLang** | ツール定義は最初の呼び出し後にキャッシュ |
| 長い共有システムプロンプト | **SGLang** | 一度のプリフィルで多くのリクエストに対応 |
| リクエストごとにユニークなプロンプト | **vLLM** | プレフィックス再利用のメリットなし、PagedAttentionは同等に高速 |
| 最新のモデルアーキテクチャ | **vLLM** | 新しいモデルの採用がより速い |
| Blackwell GPU（B100/B200） | **vLLM** | 専用Blackwell最適化パス |
| EAGLE3投機的デコード | **vLLM** | より成熟した投機的デコードサポート |
| バッチ評価（同じテンプレート） | **SGLang** | テンプレートプレフィックスが全バリアントでキャッシュ |
| シングルユーザー、低同時実行 | いずれも | 両方とも良好に動作、慣れ親しんだ方で選択 |

## 設定例

### 長い取得コンテキスト付きRAGパイプライン

すべてのリクエストが同じシステムプロンプトと大きな取得ドキュメントチャンクを持つ、RAGに最適化された70Bモデルをサーブする：

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
python -m sglang.launch_server \
  --model-path meta-llama/Llama-3.1-70B-Instruct \
  --port 30000 \
  --tp 4 \
  --mem-fraction-static 0.92 \
  --context-length 16384 \
  --chunked-prefill-size 4096 \
  --enable-metrics
```

`--mem-fraction-static 0.92`は長い取得コンテキスト向けにGPUメモリのより多くをKVキャッシュに割り当てる。`--chunked-prefill-size 4096`は大きなドキュメントプリフィルが同時デコードリクエストをストールするのを防ぐ。RadixAttentionが残りを処理する — システムプロンプトとドキュメントプレフィックスは最初のリクエスト後にキャッシュされる。

### ツールスキーマ付きマルチターンチャットエージェント

呼び出しごとに同じツール定義を送信するエージェント向けにモデルをサーブする：

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
python -m sglang.launch_server \
  --model-path meta-llama/Llama-3.1-8B-Instruct \
  --port 30000 \
  --tp 1 \
  --mem-fraction-static 0.90 \
  --context-length 32768 \
  --chunked-prefill-size 2048 \
  --enable-metrics
```

エージェントのツールスキーマ、システムプロンプト、フューショット例は呼び出し間で同一である。RadixAttentionがそのプレフィックス全体をキャッシュする。各ターンの終わりの新しいツール結果とユーザーメッセージのみが新しいプリフィルを必要とする。32Kコンテキストで、マルチターン会話は制限に達する前に数十ターンを実行できる。

### 高スループットバッチ評価

最大スループットで数千の入力に対して同じプロンプトテンプレートを実行する：

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
python -m sglang.launch_server \
  --model-path meta-llama/Llama-3.1-70B-Instruct \
  --port 30000 \
  --tp 8 \
  --mem-fraction-static 0.90 \
  --context-length 8192 \
  --chunked-prefill-size 4096 \
  --enable-metrics
```

プロンプトテンプレートは一度プリフィルされキャッシュされる。各リクエストはユニークな変数置換のみをプリフィルする。テンソル並列化で8 GPUにまたがり、バッチスループットはデコードが支配的 — プリフィルオーバーヘッドはほぼ排除される。

> [!WARNING]
>
> **セキュリティ勧告 — Qwen VL動画前処理。** v0.5.21までのSGLangには、Qwen VL動画前処理にメモリ枯渇サービス不能の脆弱性がある。細工されたリクエストが動画フレームデコード中に無制限のメモリ割り当てをトリガーする可能性がある。Qwen VLモデルをサーブする場合は、アップストリームのパッチを適用するか、修正を含むバージョンにアップグレードする。すぐにアップグレードできない場合は、SGLangサーバーへのアクセスを信頼できる呼び出し元のみに制限すること。

## ネイティブdecisions API

SGLang v0.5.21は、OllamaおよびLM Studioと同じパターンに従う**ネイティブdecisions API**を追加した。これにより、クライアントは利用可能なモデルのクエリ、モデルステータスの確認、一貫したインターフェースを通じたデプロイメント管理を行える — 複数のローカルバックエンドと通信するツールを構築する場合に有用。

API surfaceは新しく進化中のため、正確なエンドポイントパスとリクエスト/レスポンス形式についてはSGLangリリースノートを確認すること。

## Tokios経由でSGLangを接続する

SGLangが稼働したら、Tokiosコネクターはインバウンドポートを開かずにリモートクライアントへ公開する。コネクターは`https://api.tokios.com`にダイヤルアウトし、localhostのSGLangのOpenAI互換`/v1`エンドポイントにリクエストを転送する。完全なセットアップウォークスルーについては[SGLangリモートアクセス](/ja/guides/sglang-remote-access.md)を参照。

> **[SGLangリモートアクセス](/ja/guides/sglang-remote-access.md)**
>
> Tokios経由でSGLangを接続し、認証済みリモートアクセスを実現。

> **[vLLMリモートアクセス](/ja/guides/vllm-remote-access.md)**
>
> vLLM向けも同じパターン — セットアップを並べて比較。

> **[投機的デコード](/ja/guides/speculative-decoding.md)**
>
> ドラフトモデル、n-grams、MTP、EAGLEでデコードを高速化。

> **[デプロイメントのベンチマーク](/ja/guides/benchmark-your-deployment.md)**
>
> 設定間でのTTFT、スループット、レイテンシを測定。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.