OpenAI APIs - Completions#
SGLang provides OpenAI-compatible APIs to enable a smooth transition from OpenAI services to self-hosted local models. A complete reference for the API is available in the OpenAI API Reference.
This tutorial covers the following popular APIs:
chat/completionscompletions
Check out other tutorials to learn about vision APIs for vision-language models and embedding APIs for embedding models.
Launch A Server#
Launch the server in your terminal and wait for it to initialize.
[1]:
from sglang.test.doc_patch import launch_server_cmd
from sglang.utils import wait_for_server, print_highlight, terminate_process
server_process, port = launch_server_cmd(
"python3 -m sglang.launch_server --model-path qwen/qwen2.5-0.5b-instruct --host 0.0.0.0 --log-level warning"
)
wait_for_server(f"http://localhost:{port}")
print(f"Server started on http://localhost:{port}")
[2025-11-02 05:31:51] INFO utils.py:148: Note: detected 112 virtual cores but NumExpr set to maximum of 64, check "NUMEXPR_MAX_THREADS" environment variable.
[2025-11-02 05:31:51] INFO utils.py:151: Note: NumExpr detected 112 cores but "NUMEXPR_MAX_THREADS" not set, so enforcing safe limit of 16.
[2025-11-02 05:31:51] INFO utils.py:164: NumExpr defaulting to 16 threads.
[2025-11-02 05:32:05] INFO utils.py:148: Note: detected 112 virtual cores but NumExpr set to maximum of 64, check "NUMEXPR_MAX_THREADS" environment variable.
[2025-11-02 05:32:05] INFO utils.py:151: Note: NumExpr detected 112 cores but "NUMEXPR_MAX_THREADS" not set, so enforcing safe limit of 16.
[2025-11-02 05:32:05] INFO utils.py:164: NumExpr defaulting to 16 threads.
[2025-11-02 05:32:07] WARNING server_args.py:1153: Attention backend not explicitly specified. Use fa3 backend by default.
[2025-11-02 05:32:07] INFO trace.py:52: opentelemetry package is not installed, tracing disabled
[2025-11-02 05:32:14] INFO utils.py:148: Note: detected 112 virtual cores but NumExpr set to maximum of 64, check "NUMEXPR_MAX_THREADS" environment variable.
[2025-11-02 05:32:14] INFO utils.py:151: Note: NumExpr detected 112 cores but "NUMEXPR_MAX_THREADS" not set, so enforcing safe limit of 16.
[2025-11-02 05:32:14] INFO utils.py:164: NumExpr defaulting to 16 threads.
[2025-11-02 05:32:14] INFO utils.py:148: Note: detected 112 virtual cores but NumExpr set to maximum of 64, check "NUMEXPR_MAX_THREADS" environment variable.
[2025-11-02 05:32:14] INFO utils.py:151: Note: NumExpr detected 112 cores but "NUMEXPR_MAX_THREADS" not set, so enforcing safe limit of 16.
[2025-11-02 05:32:14] INFO utils.py:164: NumExpr defaulting to 16 threads.
[2025-11-02 05:32:15] INFO trace.py:52: opentelemetry package is not installed, tracing disabled
[2025-11-02 05:32:15] INFO trace.py:52: opentelemetry package is not installed, tracing disabled
[Gloo] Rank 0 is connected to 0 peer ranks. Expected number of connected peer ranks is : 0
[Gloo] Rank 0 is connected to 0 peer ranks. Expected number of connected peer ranks is : 0
[Gloo] Rank 0 is connected to 0 peer ranks. Expected number of connected peer ranks is : 0
[Gloo] Rank 0 is connected to 0 peer ranks. Expected number of connected peer ranks is : 0
/usr/local/lib/python3.10/dist-packages/pydantic/_internal/_generate_schema.py:2249: UnsupportedFieldAttributeWarning: The 'repr' attribute with value False was provided to the `Field()` function, which has no effect in the context it was used. 'repr' is field-specific metadata, and can only be attached to a model field using `Annotated` metadata or by assignment. This may have happened because an `Annotated` type alias using the `type` statement was used, or if the `Field()` function was attached to a single member of a union type.
warnings.warn(
/usr/local/lib/python3.10/dist-packages/pydantic/_internal/_generate_schema.py:2249: UnsupportedFieldAttributeWarning: The 'frozen' attribute with value True was provided to the `Field()` function, which has no effect in the context it was used. 'frozen' is field-specific metadata, and can only be attached to a model field using `Annotated` metadata or by assignment. This may have happened because an `Annotated` type alias using the `type` statement was used, or if the `Field()` function was attached to a single member of a union type.
warnings.warn(
Loading safetensors checkpoint shards: 0% Completed | 0/1 [00:00<?, ?it/s]
Loading safetensors checkpoint shards: 100% Completed | 1/1 [00:00<00:00, 4.05it/s]
Loading safetensors checkpoint shards: 100% Completed | 1/1 [00:00<00:00, 4.05it/s]
Capturing batches (bs=1 avail_mem=72.85 GB): 100%|██████████| 3/3 [00:00<00:00, 10.99it/s]
NOTE: Typically, the server runs in a separate terminal.
In this notebook, we run the server and notebook code together, so their outputs are combined.
To improve clarity, the server logs are displayed in the original black color, while the notebook outputs are highlighted in blue.
To reduce the log length, we set the log level to warning for the server, the default log level is info.
We are running those notebooks in a CI environment, so the throughput is not representative of the actual performance.
Server started on http://localhost:31670
Chat Completions#
Usage#
The server fully implements the OpenAI API. It will automatically apply the chat template specified in the Hugging Face tokenizer, if one is available. You can also specify a custom chat template with --chat-template when launching the server.
[2]:
import openai
client = openai.Client(base_url=f"http://127.0.0.1:{port}/v1", api_key="None")
response = client.chat.completions.create(
model="qwen/qwen2.5-0.5b-instruct",
messages=[
{"role": "user", "content": "List 3 countries and their capitals."},
],
temperature=0,
max_tokens=64,
)
print_highlight(f"Response: {response}")
Model Thinking/Reasoning Support#
Some models support internal reasoning or thinking processes that can be exposed in the API response. SGLang provides unified support for various reasoning models through the chat_template_kwargs parameter and compatible reasoning parsers.
Supported Models and Configuration#
Model Family |
Chat Template Parameter |
Reasoning Parser |
Notes |
|---|---|---|---|
DeepSeek-R1 (R1, R1-0528, R1-Distill) |
|
|
Standard reasoning models |
DeepSeek-V3.1 |
|
|
Hybrid model (thinking/non-thinking modes) |
Qwen3 (standard) |
|
|
Hybrid model (thinking/non-thinking modes) |
Qwen3-Thinking |
N/A (always enabled) |
|
Always generates reasoning |
Kimi |
N/A (always enabled) |
|
Kimi thinking models |
Gpt-Oss |
N/A (always enabled) |
|
Gpt-Oss thinking models |
Basic Usage#
To enable reasoning output, you need to:
Launch the server with the appropriate reasoning parser
Set the model-specific parameter in
chat_template_kwargsOptionally use
separate_reasoning: Falseto not get reasoning content separately (default toTrue)
Note for Qwen3-Thinking models: These models always generate thinking content and do not support the enable_thinking parameter. Use --reasoning-parser qwen3-thinking or --reasoning-parser qwen3 to parse the thinking content.
Example: Qwen3 Models#
# Launch server:
# python3 -m sglang.launch_server --model Qwen/Qwen3-4B --reasoning-parser qwen3
from openai import OpenAI
client = OpenAI(
api_key="EMPTY",
base_url=f"http://127.0.0.1:30000/v1",
)
model = "Qwen/Qwen3-4B"
messages = [{"role": "user", "content": "How many r's are in 'strawberry'?"}]
response = client.chat.completions.create(
model=model,
messages=messages,
extra_body={
"chat_template_kwargs": {"enable_thinking": True},
"separate_reasoning": True
}
)
print("Reasoning:", response.choices[0].message.reasoning_content)
print("-"*100)
print("Answer:", response.choices[0].message.content)
ExampleOutput:
Reasoning: Okay, so the user is asking how many 'r's are in the word 'strawberry'. Let me think. First, I need to make sure I have the word spelled correctly. Strawberry... S-T-R-A-W-B-E-R-R-Y. Wait, is that right? Let me break it down.
Starting with 'strawberry', let's write out the letters one by one. S, T, R, A, W, B, E, R, R, Y. Hmm, wait, that's 10 letters. Let me check again. S (1), T (2), R (3), A (4), W (5), B (6), E (7), R (8), R (9), Y (10). So the letters are S-T-R-A-W-B-E-R-R-Y.
...
Therefore, the answer should be three R's in 'strawberry'. But I need to make sure I'm not counting any other letters as R. Let me check again. S, T, R, A, W, B, E, R, R, Y. No other R's. So three in total. Yeah, that seems right.
----------------------------------------------------------------------------------------------------
Answer: The word "strawberry" contains **three** letters 'r'. Here's the breakdown:
1. **S-T-R-A-W-B-E-R-R-Y**
- The **third letter** is 'R'.
- The **eighth and ninth letters** are also 'R's.
Thus, the total count is **3**.
**Answer:** 3.
Note: Setting "enable_thinking": False (or omitting it) will result in reasoning_content being None. Qwen3-Thinking models always generate reasoning content and don’t support the enable_thinking parameter.
Logit Bias Support#
SGLang supports the logit_bias parameter for both chat completions and completions APIs. This parameter allows you to modify the likelihood of specific tokens being generated by adding bias values to their logits. The bias values can range from -100 to 100, where:
Positive values (0 to 100) increase the likelihood of the token being selected
Negative values (-100 to 0) decrease the likelihood of the token being selected
-100 effectively prevents the token from being generated
The logit_bias parameter accepts a dictionary where keys are token IDs (as strings) and values are the bias amounts (as floats).
Getting Token IDs#
To use logit_bias effectively, you need to know the token IDs for the words you want to bias. Here’s how to get token IDs:
# Get tokenizer to find token IDs
import tiktoken
# For OpenAI models, use the appropriate encoding
tokenizer = tiktoken.encoding_for_model("gpt-3.5-turbo") # or your model
# Get token IDs for specific words
word = "sunny"
token_ids = tokenizer.encode(word)
print(f"Token IDs for '{word}': {token_ids}")
# For SGLang models, you can access the tokenizer through the client
# and get token IDs for bias
Important: The logit_bias parameter uses token IDs as string keys, not the actual words.
Example: DeepSeek-V3 Models#
DeepSeek-V3 models support thinking mode through the thinking parameter:
# Launch server:
# python3 -m sglang.launch_server --model deepseek-ai/DeepSeek-V3.1 --tp 8 --reasoning-parser deepseek-v3
from openai import OpenAI
client = OpenAI(
api_key="EMPTY",
base_url=f"http://127.0.0.1:30000/v1",
)
model = "deepseek-ai/DeepSeek-V3.1"
messages = [{"role": "user", "content": "How many r's are in 'strawberry'?"}]
response = client.chat.completions.create(
model=model,
messages=messages,
extra_body={
"chat_template_kwargs": {"thinking": True},
"separate_reasoning": True
}
)
print("Reasoning:", response.choices[0].message.reasoning_content)
print("-"*100)
print("Answer:", response.choices[0].message.content)
Example Output:
Reasoning: First, the question is: "How many r's are in 'strawberry'?"
I need to count the number of times the letter 'r' appears in the word "strawberry".
Let me write out the word: S-T-R-A-W-B-E-R-R-Y.
Now, I'll go through each letter and count the 'r's.
...
So, I have three 'r's in "strawberry".
I should double-check. The word is spelled S-T-R-A-W-B-E-R-R-Y. The letters are at positions: 3, 8, and 9 are 'r's. Yes, that's correct.
Therefore, the answer should be 3.
----------------------------------------------------------------------------------------------------
Answer: The word "strawberry" contains **3** instances of the letter "r". Here's a breakdown for clarity:
- The word is spelled: S-T-R-A-W-B-E-R-R-Y
- The "r" appears at the 3rd, 8th, and 9th positions.
Note: DeepSeek-V3 models use the thinking parameter (not enable_thinking) to control reasoning output.
[3]:
# Example with logit_bias parameter
# Note: You need to get the actual token IDs from your tokenizer
# For demonstration, we'll use some example token IDs
response = client.chat.completions.create(
model="qwen/qwen2.5-0.5b-instruct",
messages=[
{"role": "user", "content": "Complete this sentence: The weather today is"}
],
temperature=0.7,
max_tokens=20,
logit_bias={
"12345": 50, # Increase likelihood of token ID 12345
"67890": -50, # Decrease likelihood of token ID 67890
"11111": 25, # Slightly increase likelihood of token ID 11111
},
)
print_highlight(f"Response with logit bias: {response.choices[0].message.content}")
Parameters#
The chat completions API accepts OpenAI Chat Completions API’s parameters. Refer to OpenAI Chat Completions API for more details.
SGLang extends the standard API with the extra_body parameter, allowing for additional customization. One key option within extra_body is chat_template_kwargs, which can be used to pass arguments to the chat template processor.
[4]:
response = client.chat.completions.create(
model="qwen/qwen2.5-0.5b-instruct",
messages=[
{
"role": "system",
"content": "You are a knowledgeable historian who provides concise responses.",
},
{"role": "user", "content": "Tell me about ancient Rome"},
{
"role": "assistant",
"content": "Ancient Rome was a civilization centered in Italy.",
},
{"role": "user", "content": "What were their major achievements?"},
],
temperature=0.3, # Lower temperature for more focused responses
max_tokens=128, # Reasonable length for a concise response
top_p=0.95, # Slightly higher for better fluency
presence_penalty=0.2, # Mild penalty to avoid repetition
frequency_penalty=0.2, # Mild penalty for more natural language
n=1, # Single response is usually more stable
seed=42, # Keep for reproducibility
)
print_highlight(response.choices[0].message.content)
1. The construction of the Colosseum in Rome, which was the largest amphitheater in the world at the time.
2. The development of Roman law, which established a system of legal principles and procedures.
3. The construction of the Pantheon, which was a temple dedicated to Jupiter and other gods.
4. The invention of the horseless carriage, which allowed for faster transportation.
Streaming mode is also supported.
Logit Bias Support#
The completions API also supports the logit_bias parameter with the same functionality as described in the chat completions section above.
[5]:
stream = client.chat.completions.create(
model="qwen/qwen2.5-0.5b-instruct",
messages=[{"role": "user", "content": "Say this is a test"}],
stream=True,
)
for chunk in stream:
if chunk.choices[0].delta.content is not None:
print(chunk.choices[0].delta.content, end="")
Yes, I'm a test created by Alibaba Cloud.
[6]:
# Example with logit_bias parameter for completions API
# Note: You need to get the actual token IDs from your tokenizer
# For demonstration, we'll use some example token IDs
response = client.completions.create(
model="qwen/qwen2.5-0.5b-instruct",
prompt="The best programming language for AI is",
temperature=0.7,
max_tokens=20,
logit_bias={
"12345": 75, # Strongly favor token ID 12345
"67890": -100, # Completely avoid token ID 67890
"11111": -25, # Slightly discourage token ID 11111
},
)
print_highlight(f"Response with logit bias: {response.choices[0].text}")
Completions#
Usage#
Completions API is similar to Chat Completions API, but without the messages parameter or chat templates.
[7]:
response = client.completions.create(
model="qwen/qwen2.5-0.5b-instruct",
prompt="List 3 countries and their capitals.",
temperature=0,
max_tokens=64,
n=1,
stop=None,
)
print_highlight(f"Response: {response}")
Parameters#
The completions API accepts OpenAI Completions API’s parameters. Refer to OpenAI Completions API for more details.
Here is an example of a detailed completions request:
[8]:
response = client.completions.create(
model="qwen/qwen2.5-0.5b-instruct",
prompt="Write a short story about a space explorer.",
temperature=0.7, # Moderate temperature for creative writing
max_tokens=150, # Longer response for a story
top_p=0.9, # Balanced diversity in word choice
stop=["\n\n", "THE END"], # Multiple stop sequences
presence_penalty=0.3, # Encourage novel elements
frequency_penalty=0.3, # Reduce repetitive phrases
n=1, # Generate one completion
seed=123, # For reproducible results
)
print_highlight(f"Response: {response}")
Structured Outputs (JSON, Regex, EBNF)#
For OpenAI compatible structured outputs API, refer to Structured Outputs for more details.
Using LoRA Adapters#
SGLang supports LoRA (Low-Rank Adaptation) adapters with OpenAI-compatible APIs. You can specify which adapter to use directly in the model parameter using the base-model:adapter-name syntax.
Server Setup:
python -m sglang.launch_server \
--model-path qwen/qwen2.5-0.5b-instruct \
--enable-lora \
--lora-paths adapter_a=/path/to/adapter_a adapter_b=/path/to/adapter_b
For more details on LoRA serving configuration, see the LoRA documentation.
API Call:
(Recommended) Use the model:adapter syntax to specify which adapter to use:
response = client.chat.completions.create(
model="qwen/qwen2.5-0.5b-instruct:adapter_a", # ← base-model:adapter-name
messages=[{"role": "user", "content": "Convert to SQL: show all users"}],
max_tokens=50,
)
Backward Compatible: Using ``extra_body``
The old extra_body method is still supported for backward compatibility:
# Backward compatible method
response = client.chat.completions.create(
model="qwen/qwen2.5-0.5b-instruct",
messages=[{"role": "user", "content": "Convert to SQL: show all users"}],
extra_body={"lora_path": "adapter_a"}, # ← old method
max_tokens=50,
)
Note: When both model:adapter and extra_body["lora_path"] are specified, the model:adapter syntax takes precedence.
[9]:
terminate_process(server_process)