README.md 22.4 KB
Newer Older
Lianmin Zheng's avatar
Lianmin Zheng committed
1
<div align="center">
2
<img src="https://raw.githubusercontent.com/sgl-project/sglang/main/assets/logo.png" alt="logo" width="400"></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
--------------------------------------------------------------------------------

Ying Sheng's avatar
Ying Sheng committed
14
| [**Blog**](https://lmsys.org/blog/2024-07-25-sglang-llama3/) | [**Paper**](https://arxiv.org/abs/2312.07104) | [**Slack**](https://join.slack.com/t/sgl-fru7574/shared_invite/zt-2ngly9muu-t37XiH87qvD~6rVBTkTEHw) |
Lianmin Zheng's avatar
Lianmin Zheng committed
15

Ying Sheng's avatar
Ying Sheng committed
16
17
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.
18
The core features include:
19
20
21
22
23

- **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.
- **Extensive Model Support**: Supports a wide range of generative models (Llama 3, Gemma 2, Mistral, QWen, DeepSeek, LLaVA, etc.) and embedding models (e5-mistral), with easy extensibility for integrating new models.
- **Active Community**: SGLang is open-source and backed by an active community with industry adoption, welcoming contributions to improve LLM and VLM serving.
Lianmin Zheng's avatar
Lianmin Zheng committed
24

Ying Sheng's avatar
Ying Sheng committed
25
## News
Yineng Zhang's avatar
Yineng Zhang committed
26
- [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/)).
Ying Sheng's avatar
Ying Sheng committed
27
28
- [2024/07] 🔥 Faster Llama3 Serving with SGLang Runtime (vs. TensorRT-LLM, vLLM) ([blog](https://lmsys.org/blog/2024-07-25-sglang-llama3/)).
- [2024/02] SGLang enables **3x faster JSON decoding** with compressed finite state machine ([blog](https://lmsys.org/blog/2024-02-05-compressed-fsm/)).
Ying Sheng's avatar
Ying Sheng committed
29

Ying Sheng's avatar
Ying Sheng committed
30
31
32
<details>
<summary>More</summary>

33
- [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
34
- [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
35
36
37
38
- [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>

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

## Install

49
50
You can install SGLang using any of the methods below.

Lianmin Zheng's avatar
Lianmin Zheng committed
51
52
### Method 1: With pip
```
53
pip install --upgrade pip
Lianmin Zheng's avatar
Lianmin Zheng committed
54
pip install "sglang[all]"
Lianmin Zheng's avatar
Lianmin Zheng committed
55

Lianmin Zheng's avatar
Lianmin Zheng committed
56
# Install FlashInfer CUDA kernels
57
pip install flashinfer -i https://flashinfer.ai/whl/cu121/torch2.4/
Lianmin Zheng's avatar
Lianmin Zheng committed
58
```
59

Lianmin Zheng's avatar
Lianmin Zheng committed
60
### Method 2: From source
Lianmin Zheng's avatar
Lianmin Zheng committed
61
```
Ying Sheng's avatar
Ying Sheng committed
62
# Use the last release branch
Yineng Zhang's avatar
Yineng Zhang committed
63
git clone -b v0.3.0 https://github.com/sgl-project/sglang.git
Lianmin Zheng's avatar
Lianmin Zheng committed
64
65
cd sglang

Lianmin Zheng's avatar
Lianmin Zheng committed
66
pip install --upgrade pip
Lianmin Zheng's avatar
Lianmin Zheng committed
67
68
pip install -e "python[all]"

Lianmin Zheng's avatar
Lianmin Zheng committed
69
# Install FlashInfer CUDA kernels
70
pip install flashinfer -i https://flashinfer.ai/whl/cu121/torch2.4/
Lianmin Zheng's avatar
Lianmin Zheng committed
71
```
72

Lianmin Zheng's avatar
Lianmin Zheng committed
73
### Method 3: Using docker
74
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).
75
Replace `<secret>` below with your huggingface hub [token](https://huggingface.co/docs/hub/en/security-tokens).
Ying Sheng's avatar
Ying Sheng committed
76

Liangsheng Yin's avatar
Liangsheng Yin committed
77
78
79
80
```bash
docker run --gpus all \
    -p 30000:30000 \
    -v ~/.cache/huggingface:/root/.cache/huggingface \
81
    --env "HF_TOKEN=<secret>" \
Liangsheng Yin's avatar
Liangsheng Yin committed
82
83
    --ipc=host \
    lmsysorg/sglang:latest \
84
    python3 -m sglang.launch_server --model-path meta-llama/Meta-Llama-3.1-8B-Instruct --host 0.0.0.0 --port 30000
Liangsheng Yin's avatar
Liangsheng Yin committed
85
86
```

87
88
### Method 4: Using docker compose

89
<details>
Dr. Artificial曾小健's avatar
Dr. Artificial曾小健 committed
90
<summary>More</summary>
91

92
93
94
95
96
> This method is recommended if you plan to serve it as a service.
> A better approach is to use the [k8s-sglang-service.yaml](./docker/k8s-sglang-service.yaml).

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

99
100
### Method 5: Run on Kubernetes or Clouds with SkyPilot

101
<details>
Dr. Artificial曾小健's avatar
Dr. Artificial曾小健 committed
102
<summary>More</summary>
103

104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
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 \
    --model-path meta-llama/Meta-Llama-3.1-8B-Instruct \
    --host 0.0.0.0 \
    --port 30000
```
128
</details>
129
130
131
132
133
134
135
136
137

```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).
138
</details>
139
140


Lianmin Zheng's avatar
Lianmin Zheng committed
141
### Common Notes
142
- [FlashInfer](https://github.com/flashinfer-ai/flashinfer) is currently one of the dependencies that must be installed for SGLang. It only supports sm75 and above. If you encounter any FlashInfer-related issues on sm75+ devices (e.g., T4, A10, A100, L4, L40S, H100), consider using Triton's kernel by `--disable-flashinfer --disable-flashinfer-sampling` and raise an issue.
Lianmin Zheng's avatar
Lianmin Zheng committed
143
- 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
144

Ying Sheng's avatar
Ying Sheng committed
145
146
147
## Backend: SGLang Runtime (SRT)
The SGLang Runtime (SRT) is an efficient serving engine.

Ying Sheng's avatar
Ying Sheng committed
148
### Quick Start
Ying Sheng's avatar
Ying Sheng committed
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
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
    }
  }'
```
166
Learn more about the argument format [here](docs/en/sampling_params.md).
Ying Sheng's avatar
Ying Sheng committed
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195

### 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)
196
197
198
199
200
201
202

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

Ying Sheng's avatar
Ying Sheng committed
205
It supports streaming, vision, and most 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
206
207

### Additional Server Arguments
208
- Add `--tp 2` to enable multi-GPU tensor parallelism. 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
209
210
211
```
python -m sglang.launch_server --model-path meta-llama/Meta-Llama-3-8B-Instruct --port 30000 --tp 2
```
212
- Add `--dp 2` to enable multi-GPU data parallelism. 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
213
214
215
```
python -m sglang.launch_server --model-path meta-llama/Meta-Llama-3-8B-Instruct --port 30000 --dp 2 --tp 2
```
216
- 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
217
218
219
```
python -m sglang.launch_server --model-path meta-llama/Meta-Llama-3-8B-Instruct --port 30000 --mem-fraction-static 0.7
```
220
221
- 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
222
```
223
python -m sglang.launch_server --model-path meta-llama/Meta-Llama-3-8B-Instruct --port 30000 --chunked-prefill-size 4096
Ying Sheng's avatar
Ying Sheng committed
224
```
225
226
227
228
- To enable torch.compile support, you can add `--enable-torch-compile`. It accelerates small models on small batch sizes.
- To enable fp8 weight quantization, you can add `--quantization fp8` on a fp16 checkpoint or directly load a fp8 checkpoint without specifying any arguments.
- To enable fp8 kv cache quanzation, you can add `--kv-cache-dtype fp8_e5m2`.
- If the model does not have a template in the Hugging Face tokenizer, you can specify a [custom chat template](docs/en/custom_chat_template.md).
229
- Add `--nnodes 2` to run tensor parallelism on multiple nodes. 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.
Ying Sheng's avatar
Ying Sheng committed
230
231
```
# Node 0
232
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
233
234

# Node 1
235
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
236
```
Lianmin Zheng's avatar
Lianmin Zheng committed
237
 
Ying Sheng's avatar
Ying Sheng committed
238
239
### Supported Models

240
**Generative Models**
241
- Llama / Llama 2 / Llama 3 / Llama 3.1
242
- Mistral / Mixtral / Mistral NeMo
Ying Sheng's avatar
Ying Sheng committed
243
244
- Gemma / Gemma 2
- Qwen / Qwen 2 / Qwen 2 MoE
245
- DeepSeek / DeepSeek 2
246
- [LLaVA-OneVision](https://llava-vl.github.io/blog/2024-08-05-llava-onevision/)
247
  - `python3 -m sglang.launch_server --model-path lmms-lab/llava-onevision-qwen2-7b-ov --port=30000 --chat-template=chatml-llava`
248
  - `python3 -m sglang.launch_server --model-path lmms-lab/llava-onevision-qwen2-72b-ov --port=30000 --tp-size=8 --chat-template=chatml-llava`
249
250
251
252
253
  - 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
254
255
256
257
258
259
260
- Yi-VL
- StableLM
- Command-R
- DBRX
- Grok
- ChatGLM
- InternLM 2
261
- Exaone 3
Ying Sheng's avatar
Ying Sheng committed
262

263
264
265
266
267
268
**Embedding Models**

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

269
Instructions for supporting a new model are [here](https://github.com/sgl-project/sglang/blob/main/docs/en/model_support.md).
Ying Sheng's avatar
Ying Sheng committed
270

Lianmin Zheng's avatar
Lianmin Zheng committed
271
#### Use Models From ModelScope
272
<details>
Dr. Artificial曾小健's avatar
Dr. Artificial曾小健 committed
273
<summary>More</summary>
274

Lianmin Zheng's avatar
Lianmin Zheng committed
275
To use a model from [ModelScope](https://www.modelscope.cn), set the environment variable SGLANG_USE_MODELSCOPE.
Lianmin Zheng's avatar
Lianmin Zheng committed
276
277
278
279
280
281
```
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
282
283
```
  
284
</details>
Lianmin Zheng's avatar
Lianmin Zheng committed
285
286

#### Run Llama 3.1 405B
Lianmin Zheng's avatar
Lianmin Zheng committed
287
<details>
Dr. Artificial曾小健's avatar
Dr. Artificial曾小健 committed
288
<summary>More</summary>
Ying Sheng's avatar
Ying Sheng committed
289
290

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

294
295
296
# 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
297

298
299
## 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
300
301
```

Lianmin Zheng's avatar
Lianmin Zheng committed
302
303
</details>

Ying Sheng's avatar
Ying Sheng committed
304
305
### Benchmark Performance

Lianmin Zheng's avatar
Lianmin Zheng committed
306
307
308
- 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
309
  ```
310
  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
311
312
313
  ```
- Benchmark online serving. Launch a server first and run the following command.
  ```
314
  python3 -m sglang.bench_serving --backend sglang --num-prompt 10
Ying Sheng's avatar
Ying Sheng committed
315
316
  ```

Ying Sheng's avatar
Ying Sheng committed
317
## Frontend: Structured Generation Language (SGLang)
318
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
319
320

### Quick Start
Lianmin Zheng's avatar
Lianmin Zheng committed
321
322
The example below shows how to use sglang to answer a mulit-turn question.

Ying Sheng's avatar
Ying Sheng committed
323
#### Using Local Models
324
First, launch a server with
Lianmin Zheng's avatar
Lianmin Zheng committed
325
```
Ying Sheng's avatar
Ying Sheng committed
326
python -m sglang.launch_server --model-path meta-llama/Meta-Llama-3-8B-Instruct --port 30000
Lianmin Zheng's avatar
Lianmin Zheng committed
327
328
```

329
330
Then, connect to the server and answer a multi-turn question.

Lianmin Zheng's avatar
Lianmin Zheng committed
331
```python
332
from sglang import function, system, user, assistant, gen, set_default_backend, RuntimeEndpoint
Lianmin Zheng's avatar
Lianmin Zheng committed
333
334
335
336
337
338
339
340
341

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

342
set_default_backend(RuntimeEndpoint("http://localhost:30000"))
Lianmin Zheng's avatar
Lianmin Zheng committed
343
344
345
346
347
348
349
350

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"])
351
352

print(state["answer_1"])
Lianmin Zheng's avatar
Lianmin Zheng committed
353
354
```

Ying Sheng's avatar
Ying Sheng committed
355
#### Using OpenAI Models
356
Set the OpenAI API Key
Lianmin Zheng's avatar
Lianmin Zheng committed
357
```
358
export OPENAI_API_KEY=sk-******
Lianmin Zheng's avatar
Lianmin Zheng committed
359
360
```

361
Then, answer a multi-turn question.
Lianmin Zheng's avatar
Lianmin Zheng committed
362
```python
363
from sglang import function, system, user, assistant, gen, set_default_backend, OpenAI
Lianmin Zheng's avatar
Lianmin Zheng committed
364
365
366
367
368
369
370
371
372

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

373
set_default_backend(OpenAI("gpt-3.5-turbo"))
Lianmin Zheng's avatar
Lianmin Zheng committed
374
375
376
377
378
379
380
381

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"])
382
383

print(state["answer_1"])
Lianmin Zheng's avatar
Lianmin Zheng committed
384
385
```

Ying Sheng's avatar
Ying Sheng committed
386
#### More Examples
Lianmin Zheng's avatar
Lianmin Zheng committed
387

388
Anthropic and VertexAI (Gemini) models are also supported.
Byron Hsu's avatar
Byron Hsu committed
389
You can find more examples at [examples/quick_start](examples/frontend_language/quick_start).
Lianmin Zheng's avatar
Lianmin Zheng committed
390

Ying Sheng's avatar
Ying Sheng committed
391
### Language Feature
Lianmin Zheng's avatar
Lianmin Zheng committed
392
393
394
395
396
To begin with, import sglang.
```python
import sglang as sgl
```

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

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

Ying Sheng's avatar
Ying Sheng committed
404
#### Control Flow
Lianmin Zheng's avatar
Lianmin Zheng committed
405
406
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
407
408
```python
@sgl.function
409
410
411
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
412
413
414

    if s["tool"] == "calculator":
        s += "The math expression is" + sgl.gen("expression")
415
416
    elif s["tool"] == "search engine":
        s += "The key word to search is" + sgl.gen("word")
Lianmin Zheng's avatar
Lianmin Zheng committed
417
```
Lianmin Zheng's avatar
Lianmin Zheng committed
418

Ying Sheng's avatar
Ying Sheng committed
419
#### Parallelism
Lianmin Zheng's avatar
Lianmin Zheng committed
420
421
422
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
423
424
425
426
427
428
429
430
```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
431
    forks = s.fork(2)
Lianmin Zheng's avatar
Lianmin Zheng committed
432
433
434
435
436
437
438
439
    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
440

Lianmin Zheng's avatar
Lianmin Zheng committed
441
#### Multi-Modality
Lianmin Zheng's avatar
Lianmin Zheng committed
442
443
Use `sgl.image` to pass an image as input.

Lianmin Zheng's avatar
Lianmin Zheng committed
444
445
```python
@sgl.function
Lianmin Zheng's avatar
Lianmin Zheng committed
446
def image_qa(s, image_file, question):
Lianmin Zheng's avatar
Lianmin Zheng committed
447
    s += sgl.user(sgl.image(image_file) + question)
Lianmin Zheng's avatar
Lianmin Zheng committed
448
    s += sgl.assistant(sgl.gen("answer", max_tokens=256)
Lianmin Zheng's avatar
Lianmin Zheng committed
449
450
```

451
See also [srt_example_llava.py](examples/frontend_language/quick_start/local_example_llava_next.py).
452

Ying Sheng's avatar
Ying Sheng committed
453
#### Constrained Decoding
454
455
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
456

Lianmin Zheng's avatar
Lianmin Zheng committed
457
```python
Lianmin Zheng's avatar
Lianmin Zheng committed
458
@sgl.function
Lianmin Zheng's avatar
Lianmin Zheng committed
459
460
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
461
    s += "A: " + sgl.gen(
Lianmin Zheng's avatar
Lianmin Zheng committed
462
463
464
465
466
        "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
467

Ying Sheng's avatar
Ying Sheng committed
468
#### JSON Decoding
Lianmin Zheng's avatar
Lianmin Zheng committed
469
Use `regex` to specify a JSON schema with a regular expression.
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490

```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
491
    s += name + " is a character in Harry Potter. Please fill in the following information about this character.\n"
492
493
494
    s += sgl.gen("json_output", max_tokens=256, regex=character_regex)
```

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

Ying Sheng's avatar
Ying Sheng committed
497
#### Batching
Lianmin Zheng's avatar
Lianmin Zheng committed
498
499
Use `run_batch` to run a batch of requests with continuous batching.

Lianmin Zheng's avatar
Lianmin Zheng committed
500
501
502
503
504
505
506
507
508
509
510
511
```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
512
    progress_bar=True
Lianmin Zheng's avatar
Lianmin Zheng committed
513
514
)
```
Lianmin Zheng's avatar
Lianmin Zheng committed
515

Ying Sheng's avatar
Ying Sheng committed
516
#### Streaming
Lianmin Zheng's avatar
Lianmin Zheng committed
517
518
Add `stream=True` to enable streaming.

Lianmin Zheng's avatar
Lianmin Zheng committed
519
520
521
522
523
524
```python
@sgl.function
def text_qa(s, question):
    s += "Q: " + question + "\n"
    s += "A:" + sgl.gen("answer", stop="\n")

525
state = text_qa.run(
Lianmin Zheng's avatar
Lianmin Zheng committed
526
    question="What is the capital of France?",
Lianmin Zheng's avatar
Lianmin Zheng committed
527
528
529
    temperature=0.1,
    stream=True
)
Lianmin Zheng's avatar
Lianmin Zheng committed
530

Lianmin Zheng's avatar
Lianmin Zheng committed
531
532
533
for out in state.text_iter():
    print(out, end="", flush=True)
```
Lianmin Zheng's avatar
Lianmin Zheng committed
534

535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
#### 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
553
#### Tips and Implementation Details
554
555
- 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
556

Ying Sheng's avatar
Ying Sheng committed
557
558
559
## Benchmark And Performance
![8b_throughput](https://lmsys.org/images/blog/sglang_llama3/8b_throughput.svg)
![70b_fp8_throughput](https://lmsys.org/images/blog/sglang_llama3/70b_fp8_throughput.svg)
Lianmin Zheng's avatar
Lianmin Zheng committed
560

Ying Sheng's avatar
Ying Sheng committed
561
Learn more at this [blog](https://lmsys.org/blog/2024-07-25-sglang-llama3/).
Lianmin Zheng's avatar
Lianmin Zheng committed
562

Lianmin Zheng's avatar
Lianmin Zheng committed
563
## Roadmap
Ying Sheng's avatar
Ying Sheng committed
564
[Development Roadmap (2024 Q3)](https://github.com/sgl-project/sglang/issues/634)
Lianmin Zheng's avatar
Lianmin Zheng committed
565
566

## Citation And Acknowledgment
Ying Sheng's avatar
Ying Sheng committed
567
568
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).