> ## 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 캐시를 사용합니다. 이로 인해 SGLang은 많은 요청이 동일한 시스템 프롬프트, 도구 스키마 또는 검색된 컨텍스트를 공유하는 워크로드 — RAG 파이프라인, 멀티턴 채팅, 에이전트 루프 — 에서 가장 강력한 오픈소스 선택입니다. 이 가이드에서는 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 캐시는 플랫 테이블이 아니라 토큰 시퀀스를 키로 하는 **radix tree**입니다. 요청이 처리한 모든 접두사가 트리에 저장됩니다. 새 요청이 도착하면 SGLang은 트리를 탐색하여 가장 긴 일치 접두사를 찾고 캐시된 KV 상태를 재사용합니다. 예를 들어 10개의 요청이 2,000토큰 시스템 프롬프트를 공유하면 프롬프트는 한 번만 프리필됩니다. 나머지 9개 요청은 바로 디코드로 이동합니다. 대화가 분기될 때 각 브랜치는 자체 캐시 노드를 가지며 어떤 깊이에서든 공유 접두사가 독립적으로 재사용됩니다. 성능 차이는 접두사가 많은 워크로드에서 큽니다. 50개의 동시 요청에서 80% 공유 접두사, SGLang은 vLLM 대비 **37% 더 낮은 TTFT**를 제공합니다. 접두사 중복이 증가할수록 이점이 커지고 모든 요청이 고유하면 줄어듭니다. > [!TIP] > > RadixAttention is not something you enable — it is how SGLang's KV cache works by default. Every request benefits automatically. The configuration flags control eviction policy, memory limits, and the Rust-backed storage backend. ## When SGLang wins 워크로드에 **높은 접두사 중복**이 있으면 SGLang을 선택하세요: * **RAG 파이프라인** — 동일한 시스템 프롬프트와 검색된 청크가 많은 쿼리에 나타납니다. RadixAttention은 프롬프트 + 문서 접두사를 한 번 캐시하고 모든 질문에 재사용합니다. * **멀티턴 대화** — 각 턴이 이전 컨텍스트를 확장합니다. 마지막 턴까지의 전체 대화 기록이 공유 접두사입니다. * **도구 스키마가 있는 에이전트 루프** — 에이전트는 매 호출 동일한 도구 정의, 퓨샷 예시 및 오케스트레이션 프롬프트를 전송합니다. SGLang은 이러한 접두사를 캐시하고 새 도구 결과만 프리필합니다. * **긴 공유 시스템 프롬프트** — 수십 또는 수백 명의 사용자가 큰 시스템 프롬프트를 공유하는 배포(고객 지원 봇, 코딩 어시스턴트, 문서 Q\&A). * **배치 평가** — 다른 변수 대체로 동일한 프롬프트 템플릿을 실행합니다. 템플릿 접두사가 캐시되고 채워진 부분만 프리필됩니다. ## When vLLM wins 워크로드가 **깊이보다 폭**을 우선시하면 vLLM을 선택하세요: * **요청별 고유 프롬프트** — 모든 요청이 공유 접두사 없이 완전히 다르면 RadixAttention이 재사용할 것이 없습니다. vLLM의 PagedAttention은 독립 요청을 동일하게 잘 처리합니다. * **폭넓은 모델 지원** — vLLM은 새 모델 아키텍처를 더 빠르게 지원합니다. 최근 출시된 모델이 필요하면 vLLM이 먼저 지원하는 경우가 많습니다. * **Blackwell GPU 최적화** — vLLM은 NVIDIA Blackwell (B100/B200/GB200) 하드웨어에 대한 전용 최적화 경로를 가집니다. Blackwell에 배포하면 vLLM이 더 많은 처리량을 추출합니다. * **EAGLE3 추론 디코딩** — vLLM의 EAGLE 통합이 더 성숙합니다. 추론 디코딩이 주요 지연 시간 레버이면 vLLM이 더 안전한 선택입니다. * **프로덕션 견고화** — vLLM은 더 큰 배포 기반과 프로덕션 서빙에서 더 오랜 실적을 가집니다. 안정성과 커뮤니티 지원이 접두사 캐싱보다 중요하면 vLLM이 기본입니다. ## Configuration flags 주요 SGLang 전용 플래그 `python -m sglang.launch_server`: | Flag | Default | Purpose | | - | - | - | | `--model-path` | (required) | HuggingFace repo id or local path to the model | | `--port` | `30000` | Listen port for the OpenAI-compatible server | | `--host` | `127.0.0.1` | Bind address — keep loopback unless a reverse proxy fronts SGLang | | `--tp` | `1` | Tensor parallelism across GPUs | | `--mem-fraction-static` | `0.88` | Fraction of GPU memory allocated to the KV cache at startup. Increase to `0.90`-`0.92` for long-context workloads if you have headroom. | | `--context-length` | model max | Override the model's maximum context length. Set this lower than the model max to reduce KV cache memory per request. | | `--chunked-prefill-size` | `-1` (auto) | Split large prefills into chunks to avoid stalling decode. Set to `2048`-`4096` for mixed workloads with long inputs. | | `--disable-radix-cache` | `false` | Disables RadixAttention entirely. You almost never want this — it removes SGLang's core advantage. | | `--enable-metrics` | `false` | Exposes Prometheus metrics at `/metrics`. Enable in production. | | `--api-key` | (none) | Require a bearer token on requests to SGLang's own server. Useful as defense in depth on loopback. | ### Rust-backed prefix caching RadixAttention 캐시 백엔드는 **v0.5.21**부터 Rust로 구현되어 기본적으로 활성화됩니다. Rust 백엔드는 이전 Python 구현을 대체하여 캐시 조회, 삽입 및 축출의 오버헤드를 줄입니다. 활성화 플래그가 필요 없습니다 — 기본 경로입니다. 문제가 발생하면 `--disable-cuda-graph`로 Python 구현으로 폴백하고 사용 버전에 대한 정확한 롤백 플래그를 SGLang 릴리스 노트에서 확인하세요. 실제로 Rust 백엔드는 안정적이고 더 빠릅니다. ## Decision matrix | Workload | Recommended runtime | Why | | - | - | - | | RAG with repeated context | **SGLang** | RadixAttention caches system prompt + retrieved chunks | | Multi-turn chat (10+ turns) | **SGLang** | Each turn extends a shared prefix | | Agent loops with tool schemas | **SGLang** | Tool definitions cached after first call | | Long shared system prompt | **SGLang** | One prefill serves many requests | | Unique prompts per request | **vLLM** | No prefix reuse benefit; PagedAttention is equally fast | | Latest model architectures | **vLLM** | Faster adoption of new models | | Blackwell GPU (B100/B200) | **vLLM** | Dedicated Blackwell optimization paths | | EAGLE3 speculative decoding | **vLLM** | More mature speculative decoding support | | Batch evaluation (same template) | **SGLang** | Template prefix cached across all variants | | Single-user, low-concurrency | Either | Both perform well; pick by familiarity | ## Example configurations ### RAG pipeline with long retrieved context 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` allocates more GPU memory to the KV cache for long retrieved contexts. `--chunked-prefill-size 4096` prevents large document prefills from stalling concurrent decode requests. RadixAttention handles the rest — the system prompt and document prefix are cached after the first request. ### Multi-turn chat agent with tool schemas 매 호출 동일한 도구 정의를 전송하는 에이전트를 위한 모델을 서빙합니다: ```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 컨텍스트로 멀티턴 대화는 한계에 도달하기 전 수십 턴을 실행할 수 있습니다. ### High-throughput batch evaluation 최대 처리량으로 수천 입력에 동일한 프롬프트 템플릿을 실행합니다: ```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] > > **Security advisory — Qwen VL video preprocessing.** SGLang through v0.5.21 has a memory exhaustion denial-of-service vulnerability in Qwen VL video preprocessing. A crafted request can trigger unbounded memory allocation during video frame decoding. If you serve Qwen VL models, apply the upstream patch or upgrade to a version that includes the fix. If you cannot upgrade immediately, restrict access to the SGLang server to trusted callers only. ## Native decisions API SGLang v0.5.21은 Ollama 및 LM Studio와 동일한 패턴을 따르는 **native decisions API**를 추가했습니다. 클라이언트가 사용 가능한 모델을 쿼리하고, 모델 상태를 확인하고, 일관된 인터페이스를 통해 배포를 관리할 수 있습니다 — 여러 로컬 백엔드와 통신하는 도구를 구축하는 경우 유용합니다. 정확한 엔드포인트 경로 및 요청/응답 형식은 SGLang 릴리스 노트를 확인하세요. API 표면이 새롭고 진화할 수 있습니다. ## Connect SGLang through Tokios SGLang이 실행되면 Tokios 커넥터는 인바운드 포트를 열지 않고 원격 클라이언트에 노출합니다. 커넥터는 `https://api.tokios.com`으로 다이얼아웃하고 localhost의 SGLang OpenAI 호환 `/v1` 엔드포인트로 요청을 전달합니다. 전체 설정 가이드는 [SGLang remote access](/ko/guides/sglang-remote-access.md)를 참조하세요. > **[SGLang remote access](/ko/guides/sglang-remote-access.md)** > > Connect SGLang through Tokios for authenticated remote access. > **[vLLM remote access](/ko/guides/vllm-remote-access.md)** > > Same pattern for vLLM — compare setups side by side. > **[Speculative decoding](/ko/guides/speculative-decoding.md)** > > Speed up decode with draft models, n-grams, MTP, and EAGLE. > **[Benchmark your deployment](/ko/guides/benchmark-your-deployment.md)** > > Measure TTFT, throughput, and latency across configurations. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.