README.md 23.7 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) | [**Join Slack**](https://join.slack.com/t/sgl-fru7574/shared_invite/zt-2ngly9muu-t37XiH87qvD~6rVBTkTEHw) | [**Join Bi-Weekly Development Meeting**](https://t.co/4BFjCLnVHq) |
Lianmin Zheng's avatar
Lianmin Zheng committed
15

Ying Sheng's avatar
Ying Sheng committed
16
17
18
19
## Upcoming Events
- [Oct. 5, 2024] Public bi-weekly development meeting. ([single day calendar invite](https://t.co/4BFjCLnVHq), [meeting link](meet.google.com/kkw-xvpk-mkj), [copy all events](https://calendar.google.com/calendar/event?action=TEMPLATE&tmeid=ODQydDRrOHNobDc5ZWRqNWdvaGE1czdyM3BfMjAyNDEwMDZUMDMwMDAwWiBzcXkxNDE1QG0&tmsrc=sqy1415%40gmail.com&scp=ALL), [meeting notes](https://docs.google.com/document/d/1xEow4eIM152xNcRxqZz9VEcOiTQo8-CEuuQ5qTmkt-E/edit?usp=sharing))
- [Oct. 11, 2024] Invited talks at AMD Advancing AI Developer Day.
- [Oct. 16, 2024] Online meetup for efficient LLM deployment and serving, co-hosted by SGLang, FlashInfer, and MLC LLM! Fill out the [Google form](https://forms.gle/B3YeedLxmrrhL1NM8) to receive the invite link.
20

Ying Sheng's avatar
Ying Sheng committed
21
## News 
Yineng Zhang's avatar
Yineng Zhang committed
22
- [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
23
24
- [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
25

Ying Sheng's avatar
Ying Sheng committed
26
27
28
<details>
<summary>More</summary>

29
- [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
30
- [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
31
32
33
34
- [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
35
36
37
38
39
40
41
42
43
44
## 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.
- **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.

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

## Install

55
56
You can install SGLang using any of the methods below.

Lianmin Zheng's avatar
Lianmin Zheng committed
57
58
### Method 1: With pip
```
59
pip install --upgrade pip
Lianmin Zheng's avatar
Lianmin Zheng committed
60
pip install "sglang[all]"
Lianmin Zheng's avatar
Lianmin Zheng committed
61

Lianmin Zheng's avatar
Lianmin Zheng committed
62
# Install FlashInfer CUDA kernels
63
pip install flashinfer -i https://flashinfer.ai/whl/cu121/torch2.4/
Lianmin Zheng's avatar
Lianmin Zheng committed
64
```
65

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

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

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

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

Liangsheng Yin's avatar
Liangsheng Yin committed
83
84
85
86
```bash
docker run --gpus all \
    -p 30000:30000 \
    -v ~/.cache/huggingface:/root/.cache/huggingface \
87
    --env "HF_TOKEN=<secret>" \
Liangsheng Yin's avatar
Liangsheng Yin committed
88
89
    --ipc=host \
    lmsysorg/sglang:latest \
90
    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
91
92
```

93
94
### Method 4: Using docker compose

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

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

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

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

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

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

```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).
144
</details>
145
146


Lianmin Zheng's avatar
Lianmin Zheng committed
147
### Common Notes
Lianmin Zheng's avatar
Lianmin Zheng committed
148
- [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
149
- 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
150

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

Ying Sheng's avatar
Ying Sheng committed
154
### Quick Start
Ying Sheng's avatar
Ying Sheng committed
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
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
172
173

Learn more about the argument specification, streaming, and multi-modal support [here](docs/en/sampling_params.md).
Ying Sheng's avatar
Ying Sheng committed
174
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

### 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)
203
204
205
206
207
208
209

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

Lianmin Zheng's avatar
Lianmin Zheng committed
212
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
213
214

### Additional Server Arguments
215
- 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
216
```
217
python -m sglang.launch_server --model-path meta-llama/Meta-Llama-3-8B-Instruct --tp 2
Ying Sheng's avatar
Ying Sheng committed
218
```
219
- 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
220
```
221
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
222
```
223
- 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
224
```
225
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
226
```
227
228
- 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
229
```
230
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
231
```
232
- To enable torch.compile acceleration, add `--enable-torch-compile`. It accelerates small models on small batch sizes.
Lianmin Zheng's avatar
Lianmin Zheng committed
233
- To enable torchao quantization, add `--torchao-config int4wo-128`. It supports various quantization strategies.
234
235
236
- 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).
237
- 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
238
239
```
# Node 0
240
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
241
242

# Node 1
243
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
244
```
Lianmin Zheng's avatar
Lianmin Zheng committed
245
 
Ying Sheng's avatar
Ying Sheng committed
246
247
### Supported Models

248
**Generative Models**
249
- Llama / Llama 2 / Llama 3 / Llama 3.1
250
- Mistral / Mixtral / Mistral NeMo
Ying Sheng's avatar
Ying Sheng committed
251
252
- Gemma / Gemma 2
- Qwen / Qwen 2 / Qwen 2 MoE
253
- DeepSeek / DeepSeek 2
Lianmin Zheng's avatar
Lianmin Zheng committed
254
- OLMoE
255
- [LLaVA-OneVision](https://llava-vl.github.io/blog/2024-08-05-llava-onevision/)
256
  - `python3 -m sglang.launch_server --model-path lmms-lab/llava-onevision-qwen2-7b-ov --port=30000 --chat-template=chatml-llava`
257
  - `python3 -m sglang.launch_server --model-path lmms-lab/llava-onevision-qwen2-72b-ov --port=30000 --tp-size=8 --chat-template=chatml-llava`
258
259
260
261
262
  - 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
263
264
265
266
267
268
269
- Yi-VL
- StableLM
- Command-R
- DBRX
- Grok
- ChatGLM
- InternLM 2
270
- Exaone 3
Vectory's avatar
Vectory committed
271
- BaiChuan2
William's avatar
William committed
272
- MiniCPM / MiniCPM 3
273
- XVERSE / XVERSE MoE
274
- SmolLM
William's avatar
William committed
275

276
277
278
279
280
281
**Embedding Models**

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

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

Lianmin Zheng's avatar
Lianmin Zheng committed
284
#### Use Models From ModelScope
285
<details>
Dr. Artificial曾小健's avatar
Dr. Artificial曾小健 committed
286
<summary>More</summary>
287

Lianmin Zheng's avatar
Lianmin Zheng committed
288
To use a model from [ModelScope](https://www.modelscope.cn), set the environment variable SGLANG_USE_MODELSCOPE.
Lianmin Zheng's avatar
Lianmin Zheng committed
289
290
291
292
293
294
```
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
295
```
296
297
298
299
300
301
302
303
304
305
306

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
307
  
308
</details>
Lianmin Zheng's avatar
Lianmin Zheng committed
309
310

#### Run Llama 3.1 405B
Lianmin Zheng's avatar
Lianmin Zheng committed
311
<details>
Dr. Artificial曾小健's avatar
Dr. Artificial曾小健 committed
312
<summary>More</summary>
Ying Sheng's avatar
Ying Sheng committed
313
314

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

318
319
320
# 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
321

322
323
## 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
324
325
```

Lianmin Zheng's avatar
Lianmin Zheng committed
326
327
</details>

Ying Sheng's avatar
Ying Sheng committed
328
329
### Benchmark Performance

Lianmin Zheng's avatar
Lianmin Zheng committed
330
331
332
- 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
333
  ```
334
  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
335
336
337
  ```
- Benchmark online serving. Launch a server first and run the following command.
  ```
338
  python3 -m sglang.bench_serving --backend sglang --num-prompt 10
Ying Sheng's avatar
Ying Sheng committed
339
340
  ```

Ying Sheng's avatar
Ying Sheng committed
341
## Frontend: Structured Generation Language (SGLang)
342
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
343
344

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

Ying Sheng's avatar
Ying Sheng committed
347
#### Using Local Models
348
First, launch a server with
Lianmin Zheng's avatar
Lianmin Zheng committed
349
```
Ying Sheng's avatar
Ying Sheng committed
350
python -m sglang.launch_server --model-path meta-llama/Meta-Llama-3-8B-Instruct --port 30000
Lianmin Zheng's avatar
Lianmin Zheng committed
351
352
```

353
354
Then, connect to the server and answer a multi-turn question.

Lianmin Zheng's avatar
Lianmin Zheng committed
355
```python
356
from sglang import function, system, user, assistant, gen, set_default_backend, RuntimeEndpoint
Lianmin Zheng's avatar
Lianmin Zheng committed
357
358
359
360
361
362
363
364
365

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

366
set_default_backend(RuntimeEndpoint("http://localhost:30000"))
Lianmin Zheng's avatar
Lianmin Zheng committed
367
368
369
370
371
372
373
374

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"])
375
376

print(state["answer_1"])
Lianmin Zheng's avatar
Lianmin Zheng committed
377
378
```

Ying Sheng's avatar
Ying Sheng committed
379
#### Using OpenAI Models
380
Set the OpenAI API Key
Lianmin Zheng's avatar
Lianmin Zheng committed
381
```
382
export OPENAI_API_KEY=sk-******
Lianmin Zheng's avatar
Lianmin Zheng committed
383
384
```

385
Then, answer a multi-turn question.
Lianmin Zheng's avatar
Lianmin Zheng committed
386
```python
387
from sglang import function, system, user, assistant, gen, set_default_backend, OpenAI
Lianmin Zheng's avatar
Lianmin Zheng committed
388
389
390
391
392
393
394
395
396

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

397
set_default_backend(OpenAI("gpt-3.5-turbo"))
Lianmin Zheng's avatar
Lianmin Zheng committed
398
399
400
401
402
403
404
405

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"])
406
407

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

Ying Sheng's avatar
Ying Sheng committed
410
#### More Examples
Lianmin Zheng's avatar
Lianmin Zheng committed
411

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

Ying Sheng's avatar
Ying Sheng committed
415
### Language Feature
Lianmin Zheng's avatar
Lianmin Zheng committed
416
417
418
419
420
To begin with, import sglang.
```python
import sglang as sgl
```

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

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

Ying Sheng's avatar
Ying Sheng committed
428
#### Control Flow
Lianmin Zheng's avatar
Lianmin Zheng committed
429
430
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
431
432
```python
@sgl.function
433
434
435
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
436
437
438

    if s["tool"] == "calculator":
        s += "The math expression is" + sgl.gen("expression")
439
440
    elif s["tool"] == "search engine":
        s += "The key word to search is" + sgl.gen("word")
Lianmin Zheng's avatar
Lianmin Zheng committed
441
```
Lianmin Zheng's avatar
Lianmin Zheng committed
442

Ying Sheng's avatar
Ying Sheng committed
443
#### Parallelism
Lianmin Zheng's avatar
Lianmin Zheng committed
444
445
446
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
447
448
449
450
451
452
453
454
```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
455
    forks = s.fork(2)
Lianmin Zheng's avatar
Lianmin Zheng committed
456
457
458
459
460
461
462
463
    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
464

Lianmin Zheng's avatar
Lianmin Zheng committed
465
#### Multi-Modality
Lianmin Zheng's avatar
Lianmin Zheng committed
466
467
Use `sgl.image` to pass an image as input.

Lianmin Zheng's avatar
Lianmin Zheng committed
468
469
```python
@sgl.function
Lianmin Zheng's avatar
Lianmin Zheng committed
470
def image_qa(s, image_file, question):
Lianmin Zheng's avatar
Lianmin Zheng committed
471
    s += sgl.user(sgl.image(image_file) + question)
Lianmin Zheng's avatar
Lianmin Zheng committed
472
    s += sgl.assistant(sgl.gen("answer", max_tokens=256)
Lianmin Zheng's avatar
Lianmin Zheng committed
473
474
```

475
See also [srt_example_llava.py](examples/frontend_language/quick_start/local_example_llava_next.py).
476

Ying Sheng's avatar
Ying Sheng committed
477
#### Constrained Decoding
478
479
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
480

Lianmin Zheng's avatar
Lianmin Zheng committed
481
```python
Lianmin Zheng's avatar
Lianmin Zheng committed
482
@sgl.function
Lianmin Zheng's avatar
Lianmin Zheng committed
483
484
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
485
    s += "A: " + sgl.gen(
Lianmin Zheng's avatar
Lianmin Zheng committed
486
487
488
489
490
        "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
491

Ying Sheng's avatar
Ying Sheng committed
492
#### JSON Decoding
Lianmin Zheng's avatar
Lianmin Zheng committed
493
Use `regex` to specify a JSON schema with a regular expression.
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514

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

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

Ying Sheng's avatar
Ying Sheng committed
521
#### Batching
Lianmin Zheng's avatar
Lianmin Zheng committed
522
523
Use `run_batch` to run a batch of requests with continuous batching.

Lianmin Zheng's avatar
Lianmin Zheng committed
524
525
526
527
528
529
530
531
532
533
534
535
```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
536
    progress_bar=True
Lianmin Zheng's avatar
Lianmin Zheng committed
537
538
)
```
Lianmin Zheng's avatar
Lianmin Zheng committed
539

Ying Sheng's avatar
Ying Sheng committed
540
#### Streaming
Lianmin Zheng's avatar
Lianmin Zheng committed
541
542
Add `stream=True` to enable streaming.

Lianmin Zheng's avatar
Lianmin Zheng committed
543
544
545
546
547
548
```python
@sgl.function
def text_qa(s, question):
    s += "Q: " + question + "\n"
    s += "A:" + sgl.gen("answer", stop="\n")

549
state = text_qa.run(
Lianmin Zheng's avatar
Lianmin Zheng committed
550
    question="What is the capital of France?",
Lianmin Zheng's avatar
Lianmin Zheng committed
551
552
553
    temperature=0.1,
    stream=True
)
Lianmin Zheng's avatar
Lianmin Zheng committed
554

Lianmin Zheng's avatar
Lianmin Zheng committed
555
556
557
for out in state.text_iter():
    print(out, end="", flush=True)
```
Lianmin Zheng's avatar
Lianmin Zheng committed
558

559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
#### 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
577
#### Tips and Implementation Details
578
579
- 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
580

Ying Sheng's avatar
Ying Sheng committed
581
582
583
## 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
584

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

Lianmin Zheng's avatar
Lianmin Zheng committed
587
## Roadmap
588
[Development Roadmap (2024 Q4)](https://github.com/sgl-project/sglang/issues/1487)
Lianmin Zheng's avatar
Lianmin Zheng committed
589
590

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