README.md 24.9 KB
Newer Older
1
<div align="center"  id="sglangtop">
Kushal Agrawal's avatar
Kushal Agrawal committed
2
<img src="https://raw.githubusercontent.com/sgl-project/sglang/main/assets/logo.png" alt="logo" width="400" margin="10px"></img>
Lianmin Zheng's avatar
Lianmin Zheng committed
3

Yineng Zhang's avatar
Yineng Zhang committed
4
5
6
7
8
9
[![PyPI](https://img.shields.io/pypi/v/sglang)](https://pypi.org/project/sglang)
![PyPI - Downloads](https://img.shields.io/pypi/dm/sglang)
[![license](https://img.shields.io/github/license/sgl-project/sglang.svg)](https://github.com/sgl-project/sglang/tree/main/LICENSE)
[![issue resolution](https://img.shields.io/github/issues-closed-raw/sgl-project/sglang)](https://github.com/sgl-project/sglang/issues)
[![open issues](https://img.shields.io/github/issues-raw/sgl-project/sglang)](https://github.com/sgl-project/sglang/issues)

Yineng Zhang's avatar
Yineng Zhang committed
10
11
</div>

Lianmin Zheng's avatar
Lianmin Zheng committed
12
13
--------------------------------------------------------------------------------

Lianmin Zheng's avatar
Lianmin Zheng committed
14
| [**Blog**](https://lmsys.org/blog/2024-07-25-sglang-llama3/) | [**Paper**](https://arxiv.org/abs/2312.07104) | [**Slides**](https://github.com/sgl-project/sgl-learning-materials/blob/main/slides/amd_dev_day_v2.pdf) | [**Learn More**](https://github.com/sgl-project/sgl-learning-materials) | [**Join Slack**](https://join.slack.com/t/sgl-fru7574/shared_invite/zt-2ngly9muu-t37XiH87qvD~6rVBTkTEHw) |
Ying Sheng's avatar
Ying Sheng committed
15
[**Join Bi-Weekly Development Meeting**](https://docs.google.com/document/d/1xEow4eIM152xNcRxqZz9VEcOiTQo8-CEuuQ5qTmkt-E/edit?usp=sharing) |
Lianmin Zheng's avatar
Lianmin Zheng committed
16

Lianmin Zheng's avatar
Lianmin Zheng committed
17
## News
Lianmin Zheng's avatar
Lianmin Zheng committed
18
19
20
- [2024/10] 🔥 The First SGLang Online Meetup ([slides](https://github.com/sgl-project/sgl-learning-materials?tab=readme-ov-file#the-first-sglang-online-meetup)).
- [2024/09] SGLang v0.3 Release: 7x Faster DeepSeek MLA, 1.5x Faster torch.compile, Multi-Image/Video LLaVA-OneVision ([blog](https://lmsys.org/blog/2024-09-04-sglang-v0-3/)).
- [2024/07] Faster Llama3 Serving with SGLang Runtime (vs. TensorRT-LLM, vLLM) ([blog](https://lmsys.org/blog/2024-07-25-sglang-llama3/)).
Ying Sheng's avatar
Ying Sheng committed
21

Ying Sheng's avatar
Ying Sheng committed
22
23
24
<details>
<summary>More</summary>

25
- [2024/02] SGLang enables **3x faster JSON decoding** with compressed finite state machine ([blog](https://lmsys.org/blog/2024-02-05-compressed-fsm/)).
26
- [2024/04] SGLang is used by the official **LLaVA-NeXT (video)** release ([blog](https://llava-vl.github.io/blog/2024-04-30-llava-next-video/)).
Ying Sheng's avatar
Ying Sheng committed
27
- [2024/01] SGLang provides up to **5x faster inference** with RadixAttention ([blog](https://lmsys.org/blog/2024-01-17-sglang/)).
Ying Sheng's avatar
Ying Sheng committed
28
29
30
31
- [2024/01] SGLang powers the serving of the official **LLaVA v1.6** release demo ([usage](https://github.com/haotian-liu/LLaVA?tab=readme-ov-file#demo)).

</details>

Ying Sheng's avatar
Ying Sheng committed
32
33
34
35
36
37
38
## About
SGLang is a fast serving framework for large language models and vision language models.
It makes your interaction with models faster and more controllable by co-designing the backend runtime and frontend language.
The core features include:

- **Fast Backend Runtime**: Provides efficient serving with RadixAttention for prefix caching, jump-forward constrained decoding, continuous batching, token attention (paged attention), tensor parallelism, FlashInfer kernels, chunked prefill, and quantization (INT4/FP8/AWQ/GPTQ).
- **Flexible Frontend Language**: Offers an intuitive interface for programming LLM applications, including chained generation calls, advanced prompting, control flow, multi-modal inputs, parallelism, and external interactions.
Lianmin Zheng's avatar
Lianmin Zheng committed
39
- **Extensive Model Support**: Supports a wide range of generative models (Llama, Gemma, Mistral, QWen, DeepSeek, LLaVA, etc.) and embedding models (e5-mistral), with easy extensibility for integrating new models.
Ying Sheng's avatar
Ying Sheng committed
40
41
- **Active Community**: SGLang is open-source and backed by an active community with industry adoption.

Lianmin Zheng's avatar
Lianmin Zheng committed
42
43
44
## Contents
- [Install](#install)
- [Backend: SGLang Runtime (SRT)](#backend-sglang-runtime-srt)
Ying Sheng's avatar
Ying Sheng committed
45
- [Frontend: Structured Generation Language (SGLang)](#frontend-structured-generation-language-sglang)
Lianmin Zheng's avatar
Lianmin Zheng committed
46
47
48
49
50
51
- [Benchmark And Performance](#benchmark-and-performance)
- [Roadmap](#roadmap)
- [Citation And Acknowledgment](#citation-and-acknowledgment)

## Install

52
53
You can install SGLang using any of the methods below.

Lianmin Zheng's avatar
Lianmin Zheng committed
54
55
### Method 1: With pip
```
56
pip install --upgrade pip
Lianmin Zheng's avatar
Lianmin Zheng committed
57
pip install "sglang[all]"
Lianmin Zheng's avatar
Lianmin Zheng committed
58

Lianmin Zheng's avatar
Lianmin Zheng committed
59
# Install FlashInfer accelerated kernels
60
pip install flashinfer -i https://flashinfer.ai/whl/cu121/torch2.4/
Lianmin Zheng's avatar
Lianmin Zheng committed
61
```
62

63
Note: Please check the [FlashInfer installation doc](https://docs.flashinfer.ai/installation.html) to install the proper version according to your PyTorch and CUDA versions.
Lianmin Zheng's avatar
Lianmin Zheng committed
64

Lianmin Zheng's avatar
Lianmin Zheng committed
65
### Method 2: From source
Lianmin Zheng's avatar
Lianmin Zheng committed
66
```
Ying Sheng's avatar
Ying Sheng committed
67
# Use the last release branch
Lianmin Zheng's avatar
Lianmin Zheng committed
68
git clone -b v0.3.4.post2 https://github.com/sgl-project/sglang.git
Lianmin Zheng's avatar
Lianmin Zheng committed
69
70
cd sglang

Lianmin Zheng's avatar
Lianmin Zheng committed
71
pip install --upgrade pip
Lianmin Zheng's avatar
Lianmin Zheng committed
72
73
pip install -e "python[all]"

Lianmin Zheng's avatar
Lianmin Zheng committed
74
# Install FlashInfer accelerated kernels
75
pip install flashinfer -i https://flashinfer.ai/whl/cu121/torch2.4/
Lianmin Zheng's avatar
Lianmin Zheng committed
76
```
77

78
Note: Please check the [FlashInfer installation doc](https://docs.flashinfer.ai/installation.html) to install the proper version according to your PyTorch and CUDA versions.
Lianmin Zheng's avatar
Lianmin Zheng committed
79

Lianmin Zheng's avatar
Lianmin Zheng committed
80
### Method 3: Using docker
81
The docker images are available on Docker Hub as [lmsysorg/sglang](https://hub.docker.com/r/lmsysorg/sglang/tags), built from [Dockerfile](https://github.com/sgl-project/sglang/tree/main/docker).
82
Replace `<secret>` below with your huggingface hub [token](https://huggingface.co/docs/hub/en/security-tokens).
Ying Sheng's avatar
Ying Sheng committed
83

Liangsheng Yin's avatar
Liangsheng Yin committed
84
85
86
87
```bash
docker run --gpus all \
    -p 30000:30000 \
    -v ~/.cache/huggingface:/root/.cache/huggingface \
88
    --env "HF_TOKEN=<secret>" \
Liangsheng Yin's avatar
Liangsheng Yin committed
89
90
    --ipc=host \
    lmsysorg/sglang:latest \
91
    python3 -m sglang.launch_server --model-path meta-llama/Llama-3.1-8B-Instruct --host 0.0.0.0 --port 30000
Liangsheng Yin's avatar
Liangsheng Yin committed
92
93
```

94
95
### Method 4: Using docker compose

96
<details>
Dr. Artificial曾小健's avatar
Dr. Artificial曾小健 committed
97
<summary>More</summary>
98

99
> This method is recommended if you plan to serve it as a service.
100
> A better approach is to use the [k8s-sglang-service.yaml](docker/k8s-sglang-service.yaml).
101

102
1. Copy the [compose.yml](docker/compose.yaml) to your local machine
103
2. Execute the command `docker compose up -d` in your terminal.
104
</details>
105

106
107
### Method 5: Run on Kubernetes or Clouds with SkyPilot

108
<details>
Dr. Artificial曾小健's avatar
Dr. Artificial曾小健 committed
109
<summary>More</summary>
110

111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
To deploy on Kubernetes or 12+ clouds, you can use [SkyPilot](https://github.com/skypilot-org/skypilot).

1. Install SkyPilot and set up Kubernetes cluster or cloud access: see [SkyPilot's documentation](https://skypilot.readthedocs.io/en/latest/getting-started/installation.html).
2. Deploy on your own infra with a single command and get the HTTP API endpoint:
<details>
<summary>SkyPilot YAML: <code>sglang.yaml</code></summary>

```yaml
# sglang.yaml
envs:
  HF_TOKEN: null

resources:
  image_id: docker:lmsysorg/sglang:latest
  accelerators: A100
  ports: 30000

run: |
  conda deactivate
  python3 -m sglang.launch_server \
131
    --model-path meta-llama/Llama-3.1-8B-Instruct \
132
133
134
    --host 0.0.0.0 \
    --port 30000
```
135
</details>
136
137
138
139
140
141
142
143
144

```bash
# Deploy on any cloud or Kubernetes cluster. Use --cloud <cloud> to select a specific cloud provider.
HF_TOKEN=<secret> sky launch -c sglang --env HF_TOKEN sglang.yaml

# Get the HTTP API endpoint
sky status --endpoint 30000 sglang
```
3. To further scale up your deployment with autoscaling and failure recovery, check out the [SkyServe + SGLang guide](https://github.com/skypilot-org/skypilot/tree/master/llm/sglang#serving-llama-2-with-sglang-for-more-traffic-using-skyserve).
145
</details>
146
147


Lianmin Zheng's avatar
Lianmin Zheng committed
148
### Common Notes
Lianmin Zheng's avatar
Lianmin Zheng committed
149
- [FlashInfer](https://github.com/flashinfer-ai/flashinfer) is the default attention kernel backend. It only supports sm75 and above. If you encounter any FlashInfer-related issues on sm75+ devices (e.g., T4, A10, A100, L4, L40S, H100), please switch to other kernels by adding `--attention-backend triton --sampling-backend pytorch` and open an issue on GitHub.
Lianmin Zheng's avatar
Lianmin Zheng committed
150
- If you only need to use the OpenAI backend, you can avoid installing other dependencies by using `pip install "sglang[openai]"`.
Ying Sheng's avatar
Ying Sheng committed
151

Ying Sheng's avatar
Ying Sheng committed
152
153
154
## Backend: SGLang Runtime (SRT)
The SGLang Runtime (SRT) is an efficient serving engine.

Ying Sheng's avatar
Ying Sheng committed
155
### Quick Start
Ying Sheng's avatar
Ying Sheng committed
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
Launch a server
```
python -m sglang.launch_server --model-path meta-llama/Meta-Llama-3-8B-Instruct --port 30000
```

Send a request
```
curl http://localhost:30000/generate \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Once upon a time,",
    "sampling_params": {
      "max_new_tokens": 16,
      "temperature": 0
    }
  }'
```
Lianmin Zheng's avatar
Lianmin Zheng committed
173
174

Learn more about the argument specification, streaming, and multi-modal support [here](docs/en/sampling_params.md).
Ying Sheng's avatar
Ying Sheng committed
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203

### OpenAI Compatible API
In addition, the server supports OpenAI-compatible APIs.

```python
import openai
client = openai.Client(
    base_url="http://127.0.0.1:30000/v1", api_key="EMPTY")

# Text completion
response = client.completions.create(
	model="default",
	prompt="The capital of France is",
	temperature=0,
	max_tokens=32,
)
print(response)

# Chat completion
response = client.chat.completions.create(
    model="default",
    messages=[
        {"role": "system", "content": "You are a helpful AI assistant"},
        {"role": "user", "content": "List 3 countries and their capitals."},
    ],
    temperature=0,
    max_tokens=64,
)
print(response)
204
205
206
207
208
209
210

# Text embedding
response = client.embeddings.create(
    model="default",
    input="How are you today",
)
print(response)
Ying Sheng's avatar
Ying Sheng committed
211
212
```

Lianmin Zheng's avatar
Lianmin Zheng committed
213
It supports streaming, vision, and almost all features of the Chat/Completions/Models/Batch endpoints specified by the [OpenAI API Reference](https://platform.openai.com/docs/api-reference/).
Ying Sheng's avatar
Ying Sheng committed
214
215

### Additional Server Arguments
216
- To enable multi-GPU tensor parallelism, add `--tp 2`. If it reports the error "peer access is not supported between these two devices", add `--enable-p2p-check` to the server launch command.
Ying Sheng's avatar
Ying Sheng committed
217
```
218
python -m sglang.launch_server --model-path meta-llama/Meta-Llama-3-8B-Instruct --tp 2
Ying Sheng's avatar
Ying Sheng committed
219
```
220
- To enable multi-GPU data parallelism, add `--dp 2`. Data parallelism is better for throughput if there is enough memory. It can also be used together with tensor parallelism. The following command uses 4 GPUs in total.
Ying Sheng's avatar
Ying Sheng committed
221
```
222
python -m sglang.launch_server --model-path meta-llama/Meta-Llama-3-8B-Instruct --dp 2 --tp 2
Ying Sheng's avatar
Ying Sheng committed
223
```
224
- If you see out-of-memory errors during serving, try to reduce the memory usage of the KV cache pool by setting a smaller value of `--mem-fraction-static`. The default value is `0.9`.
Ying Sheng's avatar
Ying Sheng committed
225
```
226
python -m sglang.launch_server --model-path meta-llama/Meta-Llama-3-8B-Instruct --mem-fraction-static 0.7
Ying Sheng's avatar
Ying Sheng committed
227
```
228
229
- See [hyperparameter_tuning.md](docs/en/hyperparameter_tuning.md) on tuning hyperparameters for better performance.
- If you see out-of-memory errors during prefill for long prompts, try to set a smaller chunked prefill size.
Ying Sheng's avatar
Ying Sheng committed
230
```
231
python -m sglang.launch_server --model-path meta-llama/Meta-Llama-3-8B-Instruct --chunked-prefill-size 4096
Ying Sheng's avatar
Ying Sheng committed
232
```
Lianmin Zheng's avatar
Lianmin Zheng committed
233
234
- To enable the experimental overlapped scheduler, add `--enable-overlap-scheduler`. It overlaps CPU scheduler with GPU computation and can accelerate almost all workloads. This does not work for constrained decoding currenly.
- To enable torch.compile acceleration, add `--enable-torch-compile`. It accelerates small models on small batch sizes. This does not work for FP8 currenly.
Lianmin Zheng's avatar
Lianmin Zheng committed
235
- To enable torchao quantization, add `--torchao-config int4wo-128`. It supports various quantization strategies.
236
237
238
- To enable fp8 weight quantization, add `--quantization fp8` on a fp16 checkpoint or directly load a fp8 checkpoint without specifying any arguments.
- To enable fp8 kv cache quantization, add `--kv-cache-dtype fp8_e5m2`.
- If the model does not have a chat template in the Hugging Face tokenizer, you can specify a [custom chat template](docs/en/custom_chat_template.md).
239
- To run tensor parallelism on multiple nodes, add `--nnodes 2`. If you have two nodes with two GPUs on each node and want to run TP=4, let `sgl-dev-0` be the hostname of the first node and `50000` be an available port, you can use the following commands. If you meet deadlock, please try to add `--disable-cuda-graph`
Ying Sheng's avatar
Ying Sheng committed
240
241
```
# Node 0
242
python -m sglang.launch_server --model-path meta-llama/Meta-Llama-3-8B-Instruct --tp 4 --nccl-init sgl-dev-0:50000 --nnodes 2 --node-rank 0
Ying Sheng's avatar
Ying Sheng committed
243
244

# Node 1
245
python -m sglang.launch_server --model-path meta-llama/Meta-Llama-3-8B-Instruct --tp 4 --nccl-init sgl-dev-0:50000 --nnodes 2 --node-rank 1
Ying Sheng's avatar
Ying Sheng committed
246
```
Lianmin Zheng's avatar
Lianmin Zheng committed
247
 
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
### Engine Without HTTP Server

We also provide an inference engine **without a HTTP server**. For example,

```python
import sglang as sgl

def main():
    prompts = [
        "Hello, my name is",
        "The president of the United States is",
        "The capital of France is",
        "The future of AI is",
    ]
    sampling_params = {"temperature": 0.8, "top_p": 0.95}
    llm = sgl.Engine(model_path="meta-llama/Meta-Llama-3.1-8B-Instruct")

    outputs = llm.generate(prompts, sampling_params)
    for prompt, output in zip(prompts, outputs):
        print("===============================")
        print(f"Prompt: {prompt}\nGenerated text: {output['text']}")

if __name__ == "__main__":
    main()
```

Lianmin Zheng's avatar
Lianmin Zheng committed
274
275
This can be used for offline batch inference and building custom servers.
You can view the full example [here](https://github.com/sgl-project/sglang/tree/main/examples/runtime/engine).
276

Ying Sheng's avatar
Ying Sheng committed
277
278
### Supported Models

279
**Generative Models**
280
- Llama / Llama 2 / Llama 3 / Llama 3.1
281
- Mistral / Mixtral / Mistral NeMo
Ying Sheng's avatar
Ying Sheng committed
282
- Gemma / Gemma 2
283
- Qwen / Qwen 2 / Qwen 2 MoE / Qwen 2 VL
284
- DeepSeek / DeepSeek 2
Lianmin Zheng's avatar
Lianmin Zheng committed
285
- OLMoE
286
- [LLaVA-OneVision](https://llava-vl.github.io/blog/2024-08-05-llava-onevision/)
287
  - `python3 -m sglang.launch_server --model-path lmms-lab/llava-onevision-qwen2-7b-ov --port=30000 --chat-template=chatml-llava`
288
  - `python3 -m sglang.launch_server --model-path lmms-lab/llava-onevision-qwen2-72b-ov --port=30000 --tp-size=8 --chat-template=chatml-llava`
289
290
291
292
293
  - Query the server with the [OpenAI Vision API](https://platform.openai.com/docs/guides/vision). See examples at [test/srt/test_vision_openai_server.py](test/srt/test_vision_openai_server.py)
- LLaVA 1.5 / 1.6 / NeXT
  - `python -m sglang.launch_server --model-path lmms-lab/llama3-llava-next-8b --port=30000 --tp-size=1 --chat-template=llava_llama_3`
  - `python -m sglang.launch_server --model-path lmms-lab/llava-next-72b --port=30000 --tp-size=8 --chat-template=chatml-llava`
  - Query the server with the [OpenAI Vision API](https://platform.openai.com/docs/guides/vision). See examples at [test/srt/test_vision_openai_server.py](test/srt/test_vision_openai_server.py)
Ying Sheng's avatar
Ying Sheng committed
294
295
296
297
298
299
300
- Yi-VL
- StableLM
- Command-R
- DBRX
- Grok
- ChatGLM
- InternLM 2
301
- Exaone 3
Vectory's avatar
Vectory committed
302
- BaiChuan2
William's avatar
William committed
303
- MiniCPM / MiniCPM 3
304
- XVERSE / XVERSE MoE
305
- SmolLM
306
- GLM-4
William's avatar
William committed
307

308
309
310
311
312
313
**Embedding Models**

- e5-mistral
- gte-Qwen2
  - `python -m sglang.launch_server --model-path Alibaba-NLP/gte-Qwen2-7B-instruct --is-embedding`

314
Instructions for supporting a new model are [here](docs/en/model_support.md).
Ying Sheng's avatar
Ying Sheng committed
315

Lianmin Zheng's avatar
Lianmin Zheng committed
316
#### Use Models From ModelScope
317
<details>
Dr. Artificial曾小健's avatar
Dr. Artificial曾小健 committed
318
<summary>More</summary>
319

Lianmin Zheng's avatar
Lianmin Zheng committed
320
To use a model from [ModelScope](https://www.modelscope.cn), set the environment variable SGLANG_USE_MODELSCOPE.
Lianmin Zheng's avatar
Lianmin Zheng committed
321
322
323
324
325
326
```
export SGLANG_USE_MODELSCOPE=true
```
Launch [Qwen2-7B-Instruct](https://www.modelscope.cn/models/qwen/qwen2-7b-instruct) Server
```
SGLANG_USE_MODELSCOPE=true python -m sglang.launch_server --model-path qwen/Qwen2-7B-Instruct --port 30000
Lianmin Zheng's avatar
Lianmin Zheng committed
327
```
328
329
330
331
332
333
334
335
336
337
338

Or start it by docker.
```bash
docker run --gpus all \
    -p 30000:30000 \
    -v ~/.cache/modelscope:/root/.cache/modelscope \
    --env "SGLANG_USE_MODELSCOPE=true" \
    --ipc=host \
    lmsysorg/sglang:latest \
    python3 -m sglang.launch_server --model-path Qwen/Qwen2.5-7B-Instruct --host 0.0.0.0 --port 30000
```
Lianmin Zheng's avatar
Lianmin Zheng committed
339
  
340
</details>
Lianmin Zheng's avatar
Lianmin Zheng committed
341
342

#### Run Llama 3.1 405B
Lianmin Zheng's avatar
Lianmin Zheng committed
343
<details>
Dr. Artificial曾小健's avatar
Dr. Artificial曾小健 committed
344
<summary>More</summary>
Ying Sheng's avatar
Ying Sheng committed
345
346

```bash
347
# Run 405B (fp8) on a single node
Ying Sheng's avatar
Ying Sheng committed
348
349
python -m sglang.launch_server --model-path meta-llama/Meta-Llama-3.1-405B-Instruct-FP8 --tp 8

350
351
352
# Run 405B (fp16) on two nodes
## on the first node, replace the `172.16.4.52:20000` with your own first node ip address and port
GLOO_SOCKET_IFNAME=eth0 python3 -m sglang.launch_server --model-path meta-llama/Meta-Llama-3.1-405B-Instruct --tp 16 --nccl-init-addr 172.16.4.52:20000 --nnodes 2 --node-rank 0 --disable-cuda-graph
Ying Sheng's avatar
Ying Sheng committed
353

354
355
## on the first node, replace the `172.16.4.52:20000` with your own first node ip address and port
GLOO_SOCKET_IFNAME=eth0 python3 -m sglang.launch_server --model-path meta-llama/Meta-Llama-3.1-405B-Instruct --tp 16 --nccl-init-addr 172.16.4.52:20000 --nnodes 2 --node-rank 1 --disable-cuda-graph
Ying Sheng's avatar
Ying Sheng committed
356
357
```

Lianmin Zheng's avatar
Lianmin Zheng committed
358
359
</details>

Ying Sheng's avatar
Ying Sheng committed
360
361
### Benchmark Performance

Lianmin Zheng's avatar
Lianmin Zheng committed
362
363
364
- Benchmark a single static batch by running the following command without launching a server. The arguments are the same as for `launch_server.py`.
  Note that this is not a dynamic batching server, so it may run out of memory for a batch size that a real server can handle.
  A real server truncates the prefill into several batches, while this unit test does not. For accurate large batch testing, please use `sglang.bench_serving` instead.
Ying Sheng's avatar
Ying Sheng committed
365
  ```
366
  python -m sglang.bench_latency --model-path meta-llama/Meta-Llama-3-8B-Instruct --batch 32 --input-len 256 --output-len 32
Ying Sheng's avatar
Ying Sheng committed
367
368
369
  ```
- Benchmark online serving. Launch a server first and run the following command.
  ```
370
  python3 -m sglang.bench_serving --backend sglang --num-prompt 10
Ying Sheng's avatar
Ying Sheng committed
371
372
  ```

Ying Sheng's avatar
Ying Sheng committed
373
## Frontend: Structured Generation Language (SGLang)
374
The frontend language can be used with local models or API models. It is an alternative to the OpenAI API. You may found it easier to use for complex prompting workflow.
Ying Sheng's avatar
Ying Sheng committed
375
376

### Quick Start
377
The example below shows how to use sglang to answer a multi-turn question.
Lianmin Zheng's avatar
Lianmin Zheng committed
378

Ying Sheng's avatar
Ying Sheng committed
379
#### Using Local Models
380
First, launch a server with
Lianmin Zheng's avatar
Lianmin Zheng committed
381
```
Ying Sheng's avatar
Ying Sheng committed
382
python -m sglang.launch_server --model-path meta-llama/Meta-Llama-3-8B-Instruct --port 30000
Lianmin Zheng's avatar
Lianmin Zheng committed
383
384
```

385
386
Then, connect to the server and answer a multi-turn question.

Lianmin Zheng's avatar
Lianmin Zheng committed
387
```python
388
from sglang import function, system, user, assistant, gen, set_default_backend, RuntimeEndpoint
Lianmin Zheng's avatar
Lianmin Zheng committed
389
390
391
392
393
394
395
396
397

@function
def multi_turn_question(s, question_1, question_2):
    s += system("You are a helpful assistant.")
    s += user(question_1)
    s += assistant(gen("answer_1", max_tokens=256))
    s += user(question_2)
    s += assistant(gen("answer_2", max_tokens=256))

398
set_default_backend(RuntimeEndpoint("http://localhost:30000"))
Lianmin Zheng's avatar
Lianmin Zheng committed
399
400
401
402
403
404
405
406

state = multi_turn_question.run(
    question_1="What is the capital of the United States?",
    question_2="List two local attractions.",
)

for m in state.messages():
    print(m["role"], ":", m["content"])
407
408

print(state["answer_1"])
Lianmin Zheng's avatar
Lianmin Zheng committed
409
410
```

Ying Sheng's avatar
Ying Sheng committed
411
#### Using OpenAI Models
412
Set the OpenAI API Key
Lianmin Zheng's avatar
Lianmin Zheng committed
413
```
414
export OPENAI_API_KEY=sk-******
Lianmin Zheng's avatar
Lianmin Zheng committed
415
416
```

417
Then, answer a multi-turn question.
Lianmin Zheng's avatar
Lianmin Zheng committed
418
```python
419
from sglang import function, system, user, assistant, gen, set_default_backend, OpenAI
Lianmin Zheng's avatar
Lianmin Zheng committed
420
421
422
423
424
425
426
427
428

@function
def multi_turn_question(s, question_1, question_2):
    s += system("You are a helpful assistant.")
    s += user(question_1)
    s += assistant(gen("answer_1", max_tokens=256))
    s += user(question_2)
    s += assistant(gen("answer_2", max_tokens=256))

429
set_default_backend(OpenAI("gpt-3.5-turbo"))
Lianmin Zheng's avatar
Lianmin Zheng committed
430
431
432
433
434
435
436
437

state = multi_turn_question.run(
    question_1="What is the capital of the United States?",
    question_2="List two local attractions.",
)

for m in state.messages():
    print(m["role"], ":", m["content"])
438
439

print(state["answer_1"])
Lianmin Zheng's avatar
Lianmin Zheng committed
440
441
```

Ying Sheng's avatar
Ying Sheng committed
442
#### More Examples
443
Anthropic and VertexAI (Gemini) models are also supported.
Byron Hsu's avatar
Byron Hsu committed
444
You can find more examples at [examples/quick_start](examples/frontend_language/quick_start).
Lianmin Zheng's avatar
Lianmin Zheng committed
445

Ying Sheng's avatar
Ying Sheng committed
446
### Language Feature
Lianmin Zheng's avatar
Lianmin Zheng committed
447
448
449
450
451
To begin with, import sglang.
```python
import sglang as sgl
```

Lianmin Zheng's avatar
Lianmin Zheng committed
452
`sglang` provides some simple primitives such as `gen`, `select`, `fork`, `image`.
Lianmin Zheng's avatar
Lianmin Zheng committed
453
454
You can implement your prompt flow in a function decorated by `sgl.function`.
You can then invoke the function with `run` or `run_batch`.
455
The system will manage the state, chat template, parallelism and batching for you.
Lianmin Zheng's avatar
Lianmin Zheng committed
456

457
The complete code for the examples below can be found at [readme_examples.py](examples/frontend_language/usage/readme_examples.py)
458

Ying Sheng's avatar
Ying Sheng committed
459
#### Control Flow
Lianmin Zheng's avatar
Lianmin Zheng committed
460
461
You can use any Python code within the function body, including control flow, nested function calls, and external libraries.

Lianmin Zheng's avatar
Lianmin Zheng committed
462
463
```python
@sgl.function
464
465
466
def tool_use(s, question):
    s += "To answer this question: " + question + ". "
    s += "I need to use a " + sgl.gen("tool", choices=["calculator", "search engine"]) + ". "
Lianmin Zheng's avatar
Lianmin Zheng committed
467
468
469

    if s["tool"] == "calculator":
        s += "The math expression is" + sgl.gen("expression")
470
471
    elif s["tool"] == "search engine":
        s += "The key word to search is" + sgl.gen("word")
Lianmin Zheng's avatar
Lianmin Zheng committed
472
```
Lianmin Zheng's avatar
Lianmin Zheng committed
473

Ying Sheng's avatar
Ying Sheng committed
474
#### Parallelism
Lianmin Zheng's avatar
Lianmin Zheng committed
475
476
477
Use `fork` to launch parallel prompts.
Because `sgl.gen` is non-blocking, the for loop below issues two generation calls in parallel.

Lianmin Zheng's avatar
Lianmin Zheng committed
478
479
480
481
482
483
484
485
```python
@sgl.function
def tip_suggestion(s):
    s += (
        "Here are two tips for staying healthy: "
        "1. Balanced Diet. 2. Regular Exercise.\n\n"
    )

Lianmin Zheng's avatar
Lianmin Zheng committed
486
    forks = s.fork(2)
Lianmin Zheng's avatar
Lianmin Zheng committed
487
488
489
490
491
492
493
494
    for i, f in enumerate(forks):
        f += f"Now, expand tip {i+1} into a paragraph:\n"
        f += sgl.gen(f"detailed_tip", max_tokens=256, stop="\n\n")

    s += "Tip 1:" + forks[0]["detailed_tip"] + "\n"
    s += "Tip 2:" + forks[1]["detailed_tip"] + "\n"
    s += "In summary" + sgl.gen("summary")
```
Lianmin Zheng's avatar
Lianmin Zheng committed
495

Lianmin Zheng's avatar
Lianmin Zheng committed
496
#### Multi-Modality
Lianmin Zheng's avatar
Lianmin Zheng committed
497
498
Use `sgl.image` to pass an image as input.

Lianmin Zheng's avatar
Lianmin Zheng committed
499
500
```python
@sgl.function
Lianmin Zheng's avatar
Lianmin Zheng committed
501
def image_qa(s, image_file, question):
Lianmin Zheng's avatar
Lianmin Zheng committed
502
    s += sgl.user(sgl.image(image_file) + question)
Lianmin Zheng's avatar
Lianmin Zheng committed
503
    s += sgl.assistant(sgl.gen("answer", max_tokens=256)
Lianmin Zheng's avatar
Lianmin Zheng committed
504
505
```

506
See also [srt_example_llava.py](examples/frontend_language/quick_start/local_example_llava_next.py).
507

Ying Sheng's avatar
Ying Sheng committed
508
#### Constrained Decoding
509
510
Use `regex` to specify a regular expression as a decoding constraint.
This is only supported for local models.
Lianmin Zheng's avatar
Lianmin Zheng committed
511

Lianmin Zheng's avatar
Lianmin Zheng committed
512
```python
Lianmin Zheng's avatar
Lianmin Zheng committed
513
@sgl.function
Lianmin Zheng's avatar
Lianmin Zheng committed
514
515
def regular_expression_gen(s):
    s += "Q: What is the IP address of the Google DNS servers?\n"
Lianmin Zheng's avatar
Lianmin Zheng committed
516
    s += "A: " + sgl.gen(
Lianmin Zheng's avatar
Lianmin Zheng committed
517
518
519
520
521
        "answer",
        temperature=0,
        regex=r"((25[0-5]|2[0-4]\d|[01]?\d\d?).){3}(25[0-5]|2[0-4]\d|[01]?\d\d?)",
    )
```
Lianmin Zheng's avatar
Lianmin Zheng committed
522

Ying Sheng's avatar
Ying Sheng committed
523
#### JSON Decoding
Lianmin Zheng's avatar
Lianmin Zheng committed
524
Use `regex` to specify a JSON schema with a regular expression.
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545

```python
character_regex = (
    r"""\{\n"""
    + r"""    "name": "[\w\d\s]{1,16}",\n"""
    + r"""    "house": "(Gryffindor|Slytherin|Ravenclaw|Hufflepuff)",\n"""
    + r"""    "blood status": "(Pure-blood|Half-blood|Muggle-born)",\n"""
    + r"""    "occupation": "(student|teacher|auror|ministry of magic|death eater|order of the phoenix)",\n"""
    + r"""    "wand": \{\n"""
    + r"""        "wood": "[\w\d\s]{1,16}",\n"""
    + r"""        "core": "[\w\d\s]{1,16}",\n"""
    + r"""        "length": [0-9]{1,2}\.[0-9]{0,2}\n"""
    + r"""    \},\n"""
    + r"""    "alive": "(Alive|Deceased)",\n"""
    + r"""    "patronus": "[\w\d\s]{1,16}",\n"""
    + r"""    "bogart": "[\w\d\s]{1,16}"\n"""
    + r"""\}"""
)

@sgl.function
def character_gen(s, name):
Lianmin Zheng's avatar
Lianmin Zheng committed
546
    s += name + " is a character in Harry Potter. Please fill in the following information about this character.\n"
547
548
549
    s += sgl.gen("json_output", max_tokens=256, regex=character_regex)
```

550
See also [json_decode.py](examples/frontend_language/usage/json_decode.py) for an additional example of specifying formats with Pydantic models.
551

Ying Sheng's avatar
Ying Sheng committed
552
#### Batching
Lianmin Zheng's avatar
Lianmin Zheng committed
553
554
Use `run_batch` to run a batch of requests with continuous batching.

Lianmin Zheng's avatar
Lianmin Zheng committed
555
556
557
558
559
560
561
562
563
564
565
566
```python
@sgl.function
def text_qa(s, question):
    s += "Q: " + question + "\n"
    s += "A:" + sgl.gen("answer", stop="\n")

states = text_qa.run_batch(
    [
        {"question": "What is the capital of the United Kingdom?"},
        {"question": "What is the capital of France?"},
        {"question": "What is the capital of Japan?"},
    ],
Lianmin Zheng's avatar
Lianmin Zheng committed
567
    progress_bar=True
Lianmin Zheng's avatar
Lianmin Zheng committed
568
569
)
```
Lianmin Zheng's avatar
Lianmin Zheng committed
570

Ying Sheng's avatar
Ying Sheng committed
571
#### Streaming
Lianmin Zheng's avatar
Lianmin Zheng committed
572
573
Add `stream=True` to enable streaming.

Lianmin Zheng's avatar
Lianmin Zheng committed
574
575
576
577
578
579
```python
@sgl.function
def text_qa(s, question):
    s += "Q: " + question + "\n"
    s += "A:" + sgl.gen("answer", stop="\n")

580
state = text_qa.run(
Lianmin Zheng's avatar
Lianmin Zheng committed
581
    question="What is the capital of France?",
Lianmin Zheng's avatar
Lianmin Zheng committed
582
583
584
    temperature=0.1,
    stream=True
)
Lianmin Zheng's avatar
Lianmin Zheng committed
585

Lianmin Zheng's avatar
Lianmin Zheng committed
586
587
588
for out in state.text_iter():
    print(out, end="", flush=True)
```
Lianmin Zheng's avatar
Lianmin Zheng committed
589

590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
#### Roles

Use `sgl.system``sgl.user` and `sgl.assistant` to set roles when using Chat models. You can also define more complex role prompts using begin and end tokens.

```python
@sgl.function
def chat_example(s):
    s += sgl.system("You are a helpful assistant.")
    # Same as: s += s.system("You are a helpful assistant.")

    with s.user():
        s += "Question: What is the capital of France?"

    s += sgl.assistant_begin()
    s += "Answer: " + sgl.gen(max_tokens=100, stop="\n")
    s += sgl.assistant_end()
```

Ying Sheng's avatar
Ying Sheng committed
608
#### Tips and Implementation Details
609
610
- The `choices` argument in `sgl.gen` is implemented by computing the [token-length normalized log probabilities](https://blog.eleuther.ai/multiple-choice-normalization/) of all choices and selecting the one with the highest probability.
- The `regex` argument in `sgl.gen` is implemented through autoregressive decoding with logit bias masking, according to the constraints set by the regex. It is compatible with `temperature=0` and `temperature != 0`.
Lianmin Zheng's avatar
Lianmin Zheng committed
611

Ying Sheng's avatar
Ying Sheng committed
612
## Benchmark And Performance
Lianmin Zheng's avatar
Lianmin Zheng committed
613
Learn more in our release blogs: [v0.2](https://lmsys.org/blog/2024-07-25-sglang-llama3/), [v0.3](https://lmsys.org/blog/2024-09-04-sglang-v0-3/).
Lianmin Zheng's avatar
Lianmin Zheng committed
614

Lianmin Zheng's avatar
Lianmin Zheng committed
615
## Roadmap
616
[Development Roadmap (2024 Q4)](https://github.com/sgl-project/sglang/issues/1487)
Lianmin Zheng's avatar
Lianmin Zheng committed
617
618

## Citation And Acknowledgment
Ying Sheng's avatar
Ying Sheng committed
619
620
Please cite our paper, [SGLang: Efficient Execution of Structured Language Model Programs](https://arxiv.org/abs/2312.07104), if you find the project useful.
We also learned from the design and reused code from the following projects: [Guidance](https://github.com/guidance-ai/guidance), [vLLM](https://github.com/vllm-project/vllm), [LightLLM](https://github.com/ModelTC/lightllm), [FlashInfer](https://github.com/flashinfer-ai/flashinfer), [Outlines](https://github.com/outlines-dev/outlines), and [LMQL](https://github.com/eth-sri/lmql).
621
622
623
624
625
626
627


<p align="center">
  <a href="#sglangtop" target="_blank">
  <bold>Back To Top </bold>
  </a>
</p>