# SGLang 部署与推理指南 您可以通过以下方式为任何大型语言模型（LLM）或微调模型提供服务 [SGLang](https://github.com/sgl-project/sglang) 以实现低延迟、高吞吐量的推理。SGLang 支持在任意 GPU 配置上进行文本、图像/视频模型推理，并支持部分 GGUF。 ### :computer:安装 SGLang 要在 NVIDIA GPU 上安装 SGLang 和 Unsloth，您可以在虚拟环境中使用下面的命令（不会破坏您其他的 Python 库） ```shellscript # 可选 使用虚拟环境 python -m venv unsloth_env source unsloth_env/bin/activate # 安装 Rust、outlines-core 然后安装 SGLang curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh source $HOME/.cargo/env && sudo apt-get install -y pkg-config libssl-dev pip install --upgrade pip && pip install uv uv pip install "sglang" && uv pip install unsloth ``` 对于 **Docker** 部署，请运行： {% code overflow="wrap" %} ```shellscript docker run --gpus all \ --shm-size 32g \ -p 30000:30000 \ -v ~/.cache/huggingface:/root/.cache/huggingface \ --env "HF_TOKEN=" \ --ipc=host \ lmsysorg/sglang:latest \ python3 -m sglang.launch_server --model-path unsloth/Llama-3.1-8B-Instruct --host 0.0.0.0 --port 30000 ``` {% endcode %} ### :bug:调试 SGLang 安装问题 注意：如果您看到下面的内容，请按说明更新 Rust 和 outlines-core [#setting-up-sglang](#setting-up-sglang "mention") {% code overflow="wrap" %} ``` 提示：这通常表示包或构建环境存在问题。 帮助：`outlines-core` (v0.1.26) 被包含是因为 `sglang` (v0.5.5.post2) 依赖 `outlines` (v0.1.11)，而 `outlines` 又依赖 `outlines-core` ``` {% endcode %} 如果您看到类似下面的 Flashinfer 问题： ``` /home/daniel/.cache/flashinfer/0.5.2/100a/generated/batch_prefill_with_kv_cache_dtype_q_bf16_dtype_kv_bf16_dtype_o_bf16_dtype_idx_i32_head_dim_qk_64_head_dim_vo_64_posenc_0_use_swa_False_use_logits_cap_False_f16qk_False/batch_prefill_ragged_kernel_mask_1.cu:1:10: fatal error: flashinfer/attention/prefill.cuh: No such file or directory 1 | #include | ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 编译终止。 ninja: 构建停止：子命令失败。 可能的解决方案： 1. 将 --mem-fraction-static 设置为较小的值（例如 0.8 或 0.7） 2. 将 --cuda-graph-max-bs 设置为较小的值（例如 16） 3. 通过不使用 --enable-torch-compile 来禁用 torch 编译 4. 通过 --disable-cuda-graph 禁用 CUDA graph。（不推荐，性能会大幅下降） 在 GitHub 上打开 issue https://github.com/sgl-project/sglang/issues/new/choose ``` 通过以下命令删除 flashinfer 缓存 `rm -rf .cache/flashinfer` 以及错误消息中列出的目录，即 `rm -rf ~/.cache/flashinfer` ### :truck:部署 SGLang 模型 要部署任意模型，例如 [unsloth/Llama-3.2-1B-Instruct](https://huggingface.co/unsloth/Llama-3.2-1B-Instruct)，请在另一个终端执行下面操作（否则会阻塞当前终端——您也可以使用 tmux）： {% code overflow="wrap" %} ```shellscript python3 -m sglang.launch_server \ --model-path unsloth/Llama-3.2-1B-Instruct \ --host 0.0.0.0 --port 30000 ``` {% endcode %}
然后您可以在另一个终端或使用 tmux 使用 OpenAI Chat 完成库来调用该模型： ```python # 通过 pip install openai 安装 openai from openai import OpenAI import json openai_client = OpenAI( base_url = "http://0.0.0.0:30000/v1", api_key = "sk-no-key-required", ) completion = openai_client.chat.completions.create( model = "unsloth/Llama-3.2-1B-Instruct", messages = [{"role": "user", "content": "What is 2+2?"},], ) print(completion.choices[0].message.content) ``` 您将得到 `2 + 2 = 4.` ### 🦥 在 SGLang 中部署 Unsloth 微调模型 微调完成后 [fine-tuning-llms-guide](https://unsloth.ai/docs/zh/kai-shi-shi-yong/fine-tuning-llms-guide "mention") 或使用我们的笔记本在 [unsloth-notebooks](https://unsloth.ai/docs/zh/kai-shi-shi-yong/unsloth-notebooks "mention")，您可以通过单一工作流程直接通过 SGLang 保存或部署您的模型。例如一个 Unsloth 微调脚本示例： ```python from unsloth import FastLanguageModel import torch model, tokenizer = FastLanguageModel.from_pretrained( model_name = "unsloth/gpt-oss-20b", max_seq_length = 2048, load_in_4bit = True, ) model = FastLanguageModel.get_peft_model(model) ``` **要为 SGLang 保存为 16 位，请使用：** ```python model.save_pretrained_merged("finetuned_model", tokenizer, save_method = "merged_16bit") ## 或 上传到 HuggingFace： model.push_to_hub_merged("hf/model", tokenizer, save_method = "merged_16bit", token = "") ``` **若只保存 LoRA 适配器**，可以使用： ```python model.save_pretrained("finetuned_model") tokenizer.save_pretrained("finetuned_model") ``` 或者直接使用我们内置的函数来完成： ```python model.save_pretrained_merged("model", tokenizer, save_method = "lora") ## 或 上传到 HuggingFace model.push_to_hub_merged("hf/model", tokenizer, save_method = "lora", token = "") ``` ### :railway\_car:gpt-oss-20b：Unsloth 与 SGLang 部署指南 下面是一个逐步教程，包含使用 Unsloth 训练 [gpt-oss](https://unsloth.ai/docs/zh/mo-xing/gpt-oss-how-to-run-and-fine-tune)-20b 并使用 SGLang 部署的说明。它包含跨多种量化格式的性能基准测试。 {% stepper %} {% step %} #### Unsloth 微调与导出格式 如果您对微调不熟，可以阅读我们的 [指南](https://unsloth.ai/docs/zh/kai-shi-shi-yong/fine-tuning-llms-guide)，或尝试 gpt-oss 20B 微调笔记本，地址在 [gpt-oss-how-to-run-and-fine-tune](https://unsloth.ai/docs/zh/mo-xing/gpt-oss-how-to-run-and-fine-tune "mention") 训练完成后，您可以将模型导出为多种格式： {% code overflow="wrap" %} ```python model.save_pretrained_merged( "finetuned_model", tokenizer, save_method = "merged_16bit", ) ## 针对 gpt-oss 的 mxfp4 转换： model.save_pretrained_merged( "finetuned_model", tokenizer, save_method = "mxfp4", #（仅适用于 gpt-oss，否则请选择 "merged_16bit"） ) ``` {% endcode %} {% endstep %} {% step %} #### 使用 SGLang 部署 我们将 gpt-oss 微调结果保存到文件夹 "finetuned\_model"，因此在新终端中，我们可以用 SGLang 将微调模型作为推理端点启动： ```shellscript python -m sglang.launch_server \ --model-path finetuned_model \ --host 0.0.0.0 --port 30002 ``` 您可能需要稍等一会儿，看到以下内容时： `捕获批次（bs=1 avail_mem=20.84 GB）：` ! {% endstep %} {% step %} #### 调用推理端点： 要调用推理端点，首先启动一个新终端。然后我们可以如下调用模型： {% code overflow="wrap" %} ```python from openai import OpenAI import json openai_client = OpenAI( base_url = "http://0.0.0.0:30002/v1", api_key = "sk-no-key-required", ) completion = openai_client.chat.completions.create( model = "finetuned_model", messages = [{"role": "user", "content": "What is 2+2?"},], ) print(completion.choices[0].message.content) ## 输出 ## # <|channel|>analysis<|message|>用户提出了一个简单的数学问题。我们应该回答 4。同时我们应遵守政策。没有问题。<|end|><|start|>assistant<|channel|>final<|message|>2 + 2 等于 4。 ``` {% endcode %} {% endstep %} {% endstepper %} ### :gem:FP8 在线量化 要使用 FP8 在线量化部署模型，从而在 SGLang 中实现 30% 到 50% 的更高吞吐量、50% 的内存节省并支持更长两倍的上下文长度，您可以执行以下操作： {% code overflow="wrap" %} ```shellscript python -m sglang.launch_server \ --model-path unsloth/Llama-3.2-1B-Instruct \ --host 0.0.0.0 --port 30002 \ --quantization fp8 \ --kv-cache-dtype fp8_e4m3 ``` {% endcode %} 您也可以使用 `--kv-cache-dtype fp8_e5m2` 该选项具有更大的动态范围，如果您遇到 FP8 推理问题可能会有所帮助。或者使用我们在以下列出的预量化 float8 量化模型： 或者下面列出的一些： {% embed url="" %} {% embed url="" %} ### ⚡ SGLang 基准测试 下面是一些您可以运行以测试微调模型性能速度的代码： ```shellscript python -m sglang.launch_server \ --model-path finetuned_model \ --host 0.0.0.0 --port 30002 ``` 然后在另一个终端或通过 tmux： ```shellscript # 批次大小=8，输入=1024，输出=1024 python -m sglang.bench_one_batch_server \ --model finetuned_model \ --base-url http://0.0.0.0:30002 \ --batch-size 8 \ --input-len 1024 \ --output-len 1024 ``` 您将看到类似下面的基准运行输出：
我们使用 B200x1 GPU 对 gpt-oss-20b 进行了测试，得到以下结果（约 2,500 标记的吞吐量） | 批次/输入/输出 | TTFT（秒） | ITL（秒） | 输入吞吐量 | 输出吞吐量 | | ----------- | ------- | ------ | ---------- | -------- | | 8/1024/1024 | 0.40 | 3.59 | 20,718.95 | 2,562.87 | | 8/8192/1024 | 0.42 | 3.74 | 154,459.01 | 2,473.84 | 请参见 以获取 SGLang 的服务器参数说明。 ### :person\_running:SGLang 交互式离线模式 您也可以在 Python 交互环境中以离线模式（即非服务器）使用 SGLang。 {% code overflow="wrap" %} ```python import sglang as sgl engine = sgl.Engine(model_path = "unsloth/Qwen3-0.6B", random_seed = 42) prompt = "Today is a sunny day and I like" sampling_params = {"temperature": 0, "max_new_tokens": 256} outputs = engine.generate(prompt, sampling_params)["text"] print(outputs) engine.shutdown() ``` {% endcode %} ### :sparkler:SGLang 中的 GGUF 有趣的是，SGLang 也支持 GGUF！ **Qwen3 MoE 仍在构建中，但大多数密集模型（Llama 3、Qwen 3、Mistral 等）均受支持。** 首先通过以下命令安装最新的 gguf Python 包： {% code overflow="wrap" %} ```shellscript pip install -e "git+https://github.com/ggml-org/llama.cpp.git#egg=gguf&subdirectory=gguf-py" # 从仓库子目录安装 Python 包 ``` {% endcode %} 然后例如在 SGLang 的离线模式中，您可以这样做： {% code overflow="wrap" %} ```python from huggingface_hub import hf_hub_download model_path = hf_hub_download( "unsloth/Qwen3-32B-GGUF", filename = "Qwen3-32B-UD-Q4_K_XL.gguf", ) import sglang as sgl engine = sgl.Engine(model_path = model_path, random_seed = 42) prompt = "Today is a sunny day and I like" sampling_params = {"temperature": 0, "max_new_tokens": 256} outputs = engine.generate(prompt, sampling_params)["text"] print(outputs) engine.shutdown() ``` {% endcode %} ### :clapper:使用 SGLang 提供高吞吐量的 GGUF 服务 首先像下面这样下载特定的 GGUF 文件： {% code overflow="wrap" %} ```python from huggingface_hub import hf_hub_download hf_hub_download("unsloth/Qwen3-32B-GGUF", filename="Qwen3-32B-UD-Q4_K_XL.gguf", local_dir=".") ``` {% endcode %} 然后提供该特定文件 `Qwen3-32B-UD-Q4_K_XL.gguf` 并使用 `--served-model-name unsloth/Qwen3-32B` 同时我们还需要通过 HuggingFace 兼容的 tokenizer，使用 `--tokenizer-path` ```shellscript python -m sglang.launch_server \ --model-path Qwen3-32B-UD-Q4_K_XL.gguf \ --host 0.0.0.0 --port 30002 \ --served-model-name unsloth/Qwen3-32B \ --tokenizer-path unsloth/Qwen3-32B ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://unsloth.ai/docs/zh/ji-chu/inference-and-deployment/sglang-guide.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.