SGLang Runtime 示例全解从 Native API 到离线引擎的多场景推理实战【免费下载链接】sglangSGLang is a high-performance serving framework for large language models and multimodal models.项目地址: https://gitcode.com/GitHub_Trending/sg/sglang本指南以 SGLang 仓库中的 examples/runtime 目录为主线系统梳理 SGLang 运行时Runtime的各类官方示例OpenAI 兼容 Native API 下的 LoRA 微调适配、响应预填充response prefill、奖励模型打分与 Chain-of-Verification 幻觉抑制以及不依赖 HTTP 服务的离线 Engine API、Hidden States 提取、多模态推理和 Token-In-Token-Out 工作流。读完本文你将掌握如何在两个终端中分别启动 SGLang 服务端与运行客户端脚本并能按需组合 Engine API 打造自定义服务。使用前须知一切示例都基于服务端 客户端双终端模式examples/runtime下的绝大多数示例遵循同一套运行范式先在一个终端启动 SGLang 服务端再在另一个终端运行示例脚本。README 明确指出 The below examples will mostly need you to start a server in a separate terminal before you can execute them. Please see in the code for detailed instruction.大多数示例需要你先在单独的终端中启动服务器详细指令请参见代码中的注释。每个脚本的 docstring 头部都写明了对应的服务端启动命令例如# 以 LoRA 示例为例见 examples/runtime/lora.py python -m sglang.launch_server \ --model meta-llama/Llama-3.1-8B-Instruct \ --enable-lora \ --lora-paths sql/path/to/sql python/path/to/python服务端默认监听http://127.0.0.1:30000客户端脚本通过 OpenAI SDKopenai.Client(base_urlhttp://127.0.0.1:30000/v1)或直接requests.post访问/v1、/generate、/classify、/vertex_generate等路由。而engine子目录下的示例则属于离线引擎模式不经过 HTTP直接在 Python 进程内构造sgl.Engine完成推理特别适合批处理、离线评测与构建自定义服务。Native APIOpenAI 兼容接口下的七类典型用法1. LoRA 适配器模型参数中的adapter:name语法examples/runtime/lora.py 演示了在 OpenAI 兼容接口下使用 LoRA 适配器的完整流程。启动服务端时需额外传入两个参数--enable-lora开启 LoRA 支持--lora-paths sql/path/to/sql python/path/to/python以名称路径的键值对形式注册适配器。脚本覆盖四种请求形态import openai client openai.Client(base_urlhttp://127.0.0.1:30000/v1, api_keyEMPTY) # 1. Chat Completions通过 model 参数中的 adapter:name 语法指定适配器 response client.chat.completions.create( modelmeta-llama/Llama-3.1-8B-Instruct:sql, # ← adapter:name 语法 messages[{role: user, content: Convert to SQL: show all users}], max_tokens50, ) # 2. Completions API 同样支持适配器 response client.completions.create( modelmeta-llama/Llama-3.1-8B-Instruct:python, promptdef fibonacci(n):, max_tokens50, ) # 3. 向后兼容通过 extra_body 显式传入 lora_path response client.chat.completions.create( modelmeta-llama/Llama-3.1-8B-Instruct, messages[{role: user, content: Convert to SQL: show all users}], extra_body{lora_path: sql}, max_tokens50, ) # 4. 不携带任何适配器使用基础模型 response client.chat.completions.create( modelmeta-llama/Llama-3.1-8B-Instruct, messages[{role: user, content: Hello!}], max_tokens30, )其中modelbase_model:adapter_name的adapter:name语法是推荐的新式写法而extra_body{lora_path: sql}是向后兼容的旧式写法。若服务端未启动脚本会捕获异常并提示检查python -m sglang.launch_server --model ... --enable-lora --lora-paths ...。2. 多模态 Embedding/v1/embeddings路由examples/runtime/multimodal_embedding.py 演示了多模态嵌入提取。服务端以嵌入模式启动python -m sglang.launch_server --model-path Alibaba-NLP/gme-Qwen2-VL-2B-Instruct --is-embedding客户端通过原生 HTTP 构造input数组其中可混合文本与图片图片既支持 URL 也支持 base64 编码import requests url http://127.0.0.1:30000 text_input Represent this image in embedding space. image_path https://huggingface.co/datasets/liuhaotian/llava-bench-in-the-wild/resolve/main/images/023.jpg payload { model: gme-qwen2-vl, input: [{text: text_input}, {image: image_path}], } response requests.post(url /v1/embeddings, jsonpayload).json() print(Embeddings:, [x.get(embedding) for x in response.get(data, [])])这里的input列表即 OpenAI Embeddings API 的扩展形态每个元素用text或image字段区分模态。与离线引擎版的 examples/runtime/engine/embedding.py 相比后者通过sgl.Engine(model_path..., is_embeddingTrue)和llm.encode(prompts)实现网络版更适合部署后由外部服务调用。3. 批量请求Chat 与 CompletionsREADME 中还列有openai_batch_chat.py与openai_batch_complete.py两个示例分别演示如何用 OpenAI 兼容接口批量处理 Chat Completion 与文本 Completion 请求。两者均可借助 OpenAI SDK 在一个客户端会话中连续提交多条请求由 SGLang 服务端统一调度批处理是压测与批量评测的常用起点。4. 响应预填充continue_final_message参数examples/runtime/openai_chat_with_response_prefill.py 是 README 中重点加粗介绍的示例演示了 Anthropic 风格的 prefill Claudes response 技巧在 SGLang 中的实现启用continue_final_message后对话中最后一条不完整的assistant 消息会被移除其内容作为 prefill 喂给模型使模型续写这条消息而不是开启全新一轮。启动服务端后python -m sglang.launch_server --model-path meta-llama/Llama-3.1-8B-Instruct --port 30000运行脚本即可看到两种行为的对比import openai client openai.Client(base_urlhttp://127.0.0.1:30000/v1, api_keyEMPTY) messages [ {role: system, content: You are a helpful AI assistant.}, { role: user, content: Extract the name, size, price, and color from this product description as a JSON object: description The SmartHome Mini is a compact smart home assistant available in black or white for only $49.99. At just 5 inches wide, it lets you control lights, thermostats, and other connected devices via voice or app— no matter where you place it in your home. This affordable little hub brings convenient hands-free control to your smart devices. /description , }, {role: assistant, content: {\n}, # 预填充的 JSON 开头 ] # 启用 continue_final_messageassistant 消息被移除{\n 作为 prefill模型续写 JSON response_with client.chat.completions.create( modelmeta-llama/Llama-3.1-8B-Instruct, messagesmessages, temperature0, extra_body{continue_final_message: True}, ) print(response_with.choices[0].message.content) # 不启用保持默认行为模型会将其当作历史消息开启新的一轮 response_without client.chat.completions.create( modelmeta-llama/Llama-3.1-8B-Instruct, messagesmessages, temperature0, ) print(response_without.choices[0].message.content)该能力对结构化输出如强制 JSON 抽取尤其有用先由调用方写好{\n这类前缀让模型沿着既定格式续写显著提升格式命中率。5. 奖励模型打分/classify路由examples/runtime/reward_model.py 演示如何从奖励模型reward model中提取分数用于 RLHF 数据筛选等场景。服务端同样以嵌入模式启动python -m sglang.launch_server --model LxzGordon/URM-LLaMa-3.1-8B --is-embedding客户端向/classify路由提交conv字段——一个由多轮对话user/assistant 对组成的列表服务端为每段对话返回一个标量分数import requests url http://127.0.0.1:30000 PROMPT What is the range of the numeric output of a sigmoid node in a neural network? RESPONSE1 The output of a sigmoid node is bounded between -1 and 1. RESPONSE2 The output of a sigmoid node is bounded between 0 and 1. json_data { conv: [ [{role: user, content: PROMPT}, {role: assistant, content: RESPONSE1}], [{role: user, content: PROMPT}, {role: assistant, content: RESPONSE2}], ], } response requests.post(url /classify, jsonjson_data).json() print(scores:, [x[embedding] for x in response])返回结果中embedding字段承载奖励分数脚本会打印出两个候选回答各自的得分便于直观对比优劣上例中回答 2 才是正确的。6. Vertex AI 在线预测/vertex_generate路由examples/runtime/vertex_predict.py 展示了 Google Cloud Vertex AI Online Predictions 预测路由的请求/响应格式。它既可以在本地验证请求格式也提供了部署到 Vertex AI 后的 Python SDK 调用方式# 本地验证模拟 Vertex 的 instances/parameters 请求结构 import requests class LocalVertexEndpoint: def __init__(self) - None: self.base_url http://127.0.0.1:30000 def predict(self, instances, parametersNone): response requests.post( self.base_url /vertex_generate, json{instances: instances, parameters: parameters}, ) return VertexPrediction(predictionsresponse.json()[predictions]) # 单条提示词 response endpoint.predict(instances[{text: The capital of France is}]) # 多条提示词 采样参数 response endpoint.predict( instances[ {text: The capital of France is}, {text: What is a car?}, ], parameters{sampling_params: {max_new_tokens: 16}}, )脚本 docstring 同时给出了部署到 Vertex AI Endpoint 后通过 Python SDK 发送请求的写法response endpoint.predict( instances[{text: The capital of France is}, {text: What is a car?}], parameters{sampling_params: {max_new_tokens: 16}}, ) print(response.predictions)本地路由的关键在于把 SGLang 请求包装成 Vertex AI 的instancesparameters双层结构parameters.sampling_params内嵌 SGLang 采样参数实现从本地到云端的请求格式无缝迁移。7. Chain-of-VerificationCoVe用隔离会话抑制幻觉examples/runtime/chain_of_verification.py 实现了 Dhuliawala et al. (2023) 论文《Chain-of-Verification Reduces Hallucination in Large Language Models》中的Factored CoVe模式。其核心思想是验证环节在一个全新的、隔离的会话中执行不共享原始回答的任何历史与 KV-cache从而避免模型只是机械复述自己可能幻觉的回答而是真正去核查。这也正是 README 强调的 fresh, isolated session (no shared KV-cache) to avoid self-confirmation bias。完整流程分为四步步骤动作会话说明1. Draft起草将用户问题发送给模型得到初始回答独立会话2. Verify验证新开一个无历史的独立会话让模型扮演严格的事实核查者对问题 候选回答给出PASS或FAIL判定及理由全新会话无共享 KV-cache3. Refine修正若判定为 FAIL在验证会话内继续追问让模型基于批判上下文给出修正答案沿用验证会话4. Summarize可选将最终答案压缩为一段话新会话脚本提供完整的命令行参数--base-url默认http://127.0.0.1:30000/v1、--model缺省时自动从/v1/models探测、--prompt、--max-tokens、--temperature、--summarize、--quiet。例如python chain_of_verification.py --prompt What year did the Titanic sink? python chain_of_verification.py \ --base-url http://127.0.0.1:30002/v1 \ --model moonshot-v1-8k \ --prompt Who invented the telephone?实现上的一个细节值得注意脚本在提取模型输出时会同时检查content与reasoning_content字段——推理模型如 Kimi-K2.5、Qwen3在temperature0等配置下可能把正文放在reasoning_content中而content为空因此做了回退兜底。验证用的系统提示词为VERIFY_SYSTEM_PROMPT ( You are a strict fact-checker. You will be given a user question and a candidate answer. Decide whether the answer is accurate and directly addresses the question. Reply with exactly one of: PASS or FAIL, followed by a brief reason. )判定逻辑是verdict.strip().upper().startswith(PASS)即模型回复以PASS开头即视为通过验证否则进入修正环节。Engine 子目录离线引擎 API 全家桶examples/runtime/engine目录汇集了 Offline Engine API 的常见工作流示例对应的目录级说明文档为 examples/runtime/engine/readme.md。它的最大优势是无需 HTTP 服务器在进程内直接完成推理同时引擎会自动调度大批量请求以避免 OOM。启动引擎launch_engine.py与必须的__main__守卫最精简的引擎示例 examples/runtime/engine/launch_engine.pyimport sglang as sgl def main(): llm sgl.Engine(model_pathmeta-llama/Meta-Llama-3.1-8B-Instruct) llm.generate(What is the capital of France?) llm.shutdown() # 必须保留 __main__ 守卫 if __name__ __main__: main()代码注释明确解释了__main__条件的必要性SGLang 引擎使用spawn方式创建子进程spawn 每次都会启动一个全新的 Python 解释器如果缺少该守卫sgl.Engine会陷入无限循环地不断派生子进程。所有 Engine 示例含下方离线批处理、embedding、EAGLE、VLM 等都必须遵循这一约定。离线批处理offline_batch_inference.pyexamples/runtime/engine/offline_batch_inference.py 是批处理的标准模板通过ServerArgs.add_cli_args(parser)注入全部服务端命令行参数再以dataclasses.asdict(server_args)展开传给sgl.Engineimport argparse import dataclasses import sglang as sgl from sglang.srt.server_args import ServerArgs def main(server_args: ServerArgs): prompts [ Hello, my name is, The president of the United States is, The capital of France is, The future of AI is, ] sampling_params {temperature: 0.8, top_p: 0.95} llm sgl.Engine(**dataclasses.asdict(server_args)) outputs llm.generate(prompts, sampling_params) for prompt, output in zip(prompts, outputs): print() print(fPrompt: {prompt}\nGenerated text: {output[text]}) if __name__ __main__: parser argparse.ArgumentParser() ServerArgs.add_cli_args(parser) args parser.parse_args() server_args ServerArgs.from_cli_args(args) main(server_args)运行方式python3 offline_batch_inference.py --model meta-llama/Llama-3.1-8B-Instruct。当输入批次非常大时引擎会智能调度请求、高效处理并防止 OOM——这是离线引擎区别于逐个请求的关键收益。Embedding 生成examples/runtime/engine/embedding.py 展示了嵌入生成sgl.Engine(model_pathAlibaba-NLP/gte-Qwen2-1.5B-instruct, is_embeddingTrue)随后调用llm.encode(prompts)返回结果中的embedding字段即嵌入向量。与前面 Native API 的/v1/embeddings相比这里完全在进程内完成。EAGLE 投机解码examples/runtime/engine/offline_batch_inference_eagle.py 演示了基于 EAGLE 的投机解码speculative decoding。只需在构造 Engine 时指定一组投机解码参数llm sgl.Engine( model_pathmeta-llama/Llama-2-7b-chat-hf, speculative_algorithmEAGLE, speculative_draft_model_pathlmsys/sglang-EAGLE-llama2-chat-7B, speculative_num_steps3, speculative_eagle_topk4, speculative_num_draft_tokens16, cuda_graph_max_bs_decode8, ) outputs llm.generate(prompts, sampling_params)核心参数含义speculative_algorithm指定算法此处为 EAGLEspeculative_draft_model_path指向草稿模型speculative_num_steps为每轮推测步数speculative_eagle_topk为 EAGLE 每步保留的候选 token 数speculative_num_draft_tokens控制草稿 token 总量cuda_graph_max_bs_decode限定解码阶段 CUDA Graph 的最大批大小。VLM 推理examples/runtime/engine/offline_batch_inference_vlm.py 演示多模态模型离线推理。关键点是先从sglang.srt.parser.conversation的chat_templates中按chat_template参数取出对话模板用其image_token在提示词中占位再通过image_data传入图片 URLconv chat_templates[server_args.chat_template].copy() image_token conv.image_token image_url https://github.com/sgl-project/sglang/blob/main/examples/assets/example_image.png?rawtrue prompt fWhats in this image?\n{image_token} output vlm.generate( promptprompt, image_dataimage_url, sampling_params{temperature: 0.001, max_new_tokens: 30}, )运行python offline_batch_inference_vlm.py --model-path Qwen/Qwen2-VL-7B-Instruct。异步生成offline_batch_inference_async.pyexamples/runtime/engine/offline_batch_inference_async.py 展示异步生成用法engine.async_generate适用于在批处理框架上实现在线式请求既保留批量推理的吞吐又能以异步方式逐条响应。基于 Sanic 的自定义服务器custom_server.pyexamples/runtime/engine/custom_server.py 演示如何在 SGLang Engine 之上用 Sanic 搭建自定义服务同时提供非流式与流式两个端点。安装与运行步骤pip install sanic python custom_server # 仓库中实际运行命令为 python custom_server.pycurl -X POST http://localhost:8000/generate -H Content-Type: application/json -d {prompt: The Transformer architecture is...} curl -X POST http://localhost:8000/generate_stream -H Content-Type: application/json -d {prompt: The Transformer architecture is...} --no-buffer服务端实现的核心模式是复用引擎的异步接口from sanic import Sanic, text, json import sglang as sgl engine None app Sanic(sanic-server) app.route(/generate, methods[POST]) async def generate(request): prompt request.json.get(prompt) result await engine.async_generate(prompt) # async_generate 返回 dict return text(result[text]) app.route(/generate_stream, methods[POST]) async def generate_stream(request): prompt request.json.get(prompt) result await engine.async_generate(prompt, streamTrue) response await request.respond() async for chunk in result: # 流式结果是 async generator await response.send(chunk[text]) await response.eof() def run_server(): global engine engine sgl.Engine(model_pathmeta-llama/Meta-Llama-3.1-8B-Instruct) app.run(host0.0.0.0, port8000, single_processTrue)可见sgl.Engine.async_generate是构建自定义 Web 服务的统一异步入口非流式时返回 dict流式时返回 async generator。基于 FastAPI 的服务fastapi_engine_inference.pyexamples/runtime/engine/fastapi_engine_inference.py 展示如何用 FastAPI 的 lifespan 机制管理引擎生命周期。服务启动时初始化sgl.Engine请求通过engine.async_generate处理并支持MODEL_PATH/TP_SIZE环境变量配置python fastapi_engine_inference.py --model-path Qwen/Qwen2.5-0.5B-Instruct --tp_size 1 --host 127.0.0.1 --port 8000 [--startup-timeout 60]状态保存分片与远端 checkpoint该目录还包含两个模型状态保存示例save_sharded_state.py将每个 worker 的模型 state dict 直接保存为 checkpoint使大模型在张量并行tensor parallel场景下加载时每个 worker 只需读取自己的分片而非整个 checkpoint从而显著加速加载路径save_remote_state.py则将状态保存到远端存储--remote-model-save-url [protocol]://[host]:[port]/[model_name]。典型用法形如python save_sharded_state.py --model-path /path/to/load --quantization deepspeedfp --tensor-parallel-size 8 python save_remote_state.py --model-path /path/to/load --tensor-parallel-size 8 --remote-model-save-url [protocol]://[host]:[port]/[model_name]目录级说明文档examples/runtime/engine/readme.md 将上述能力归纳为五类使用场景Offline Batch Inference、Embedding Generation、Custom ServerSanic 示例、Token-In-Token-Out for RLHF、Inference Using FastAPI并指出引擎对超大批次会自动调度以避免 OOM。Hidden States提取隐藏状态的两条路径hidden_states目录见 examples/runtime/hidden_states提供隐藏状态提取示例。README 特别提醒该功能可能因 CUDA Graph 重建而降低吞吐因为服务端需要按配置的最大隐藏状态模式构建 CUDA Graph请求可以选择该模式或更弱的模式而不会触发按模式重捕图mode-dependent recapture。两条路径对应两个脚本Engine 路径hidden_states_engine.py构造引擎时传入return_hidden_states_modelast生成时在采样参数之外单独传return_hidden_stateslast结果从output[meta_info][hidden_states]取出并转为torch.bfloat16张量llm sgl.Engine( model_pathAlibaba-NLP/gte-Qwen2-1.5B-instruct, return_hidden_states_modelast, ) outputs llm.generate( prompts, sampling_paramssampling_params, return_hidden_stateslast, ) for prompt, output in zip(prompts, outputs): hidden_state torch.tensor(output[meta_info][hidden_states], dtypetorch.bfloat16) print(fPrompt: {prompt}\nGenerated text: {output[text]}\nLast hidden state: {hidden_state})Server 路径hidden_states_server.py以--return-hidden-states-mode last启动服务端然后向/generate提交请求并在请求体中携带return_hidden_states: last同样从响应meta_info.hidden_states中取回向量。脚本内部通过sglang.utils.launch_server_cmd自动拉起并回收服务进程可独立运行python hidden_states_server.py两条路径的关键参数保持一致服务端启动参数--return-hidden-states-mode决定 CUDA Graph 配置的最大模式请求级参数return_hidden_states决定本次请求实际提取的模式当前支持last即最后一层隐藏状态。Multimodal多模态输入的多模型示例multimodal目录见 examples/runtime/multimodal展示如何用 URL、本地文件或编码后的数据向多模态模型发起请求。README 概述了四类模型示例脚本模型支持能力llava_onevision_server.pyLlava-OneVisionlmms-lab/llava-onevision-qwen2-72b-ov图像、多图、视频qwen_llava_server.pyLlava-next 驱动的 Qwen-Llavalmms-lab/llava-next-72b图像、多图llama3_llava_server.pyLlava-next 驱动的 Llama3-Llavalmms-lab/llama3-llava-next-8b图像、多图pixtral_server.pyMistral Pixtralmistral-community/pixtral-12b图像、多图以 Llava-OneVision 为例服务端启动命令为python3 -m sglang.launch_server --model-path lmms-lab/llava-onevision-qwen2-72b-ov --port30000 --tp-size8 python3 llava_onevision_server.pyllava_onevision_server.py 内部较为完整包含四类测试图像流式请求OpenAI SDK 中以image_url类型携带 URLstreamTrue逐块输出多图流式请求多个image_url条目每个条目用modalities: multi-images标注配合一段文本提示模型描述两张图视频请求先用sglang.srt.utils.video_decoder.VideoDecoderWrapper解码视频用np.linspace均匀采样最多 32 帧逐帧转 JPEG 并 base64 编码以data:image/jpeg;base64,...形式 modalities: video组装进消息依赖pip install torchcodec与pip install protobuf3.20.0速度测试分别对图像与视频请求计时输出 Total / Completion / Prompt tokens 与每秒 token 数total_tokens / elapsed等。Token In, Token Out以 token 为边界的推理工作流token_in_token_out目录见 examples/runtime/token_in_token_out展示了 RLHF 等场景中常用的输入 token、输出 token工作流——调用方自行完成分词SGLang 只负责推理并返回生成的 token id全程绕开文本层。目录包含四个脚本覆盖 LLM/VLM × Engine/Server 四个组合token_in_token_out_llm_engine.pytoken_in_token_out_llm_server.pytoken_in_token_out_vlm_engine.pytoken_in_token_out_vlm_server.pyServer 版token_in_token_out_llm_server.py的关键在于服务端以--skip-tokenizer-init启动跳过分词器初始化随后向/generate提交input_idspython token_in_token_out_llm_server.py # 脚本内部自动启动服务端json_data { input_ids: token_ids_list, # 直接给 token id而非文本 sampling_params: sampling_params, } response requests.post(fhttp://localhost:{port}/generate, jsonjson_data)Engine 版token_in_token_out_llm_engine.py同样以sgl.Engine(model_pathMODEL_PATH, skip_tokenizer_initTrue)构造引擎用llm.generate(input_idstoken_ids_list, ...)推理。两个版本的输入都通过sglang.srt.utils.hf_transformers_utils.get_tokenizer(MODEL_PATH)获取 HuggingFace 分词器完成tokenizer.encode输出则读取output[output_ids]并用tokenizer.decode还原文本。VLM 版如token_in_token_out_vlm_server.py则引入图像 token 的处理通过sglang.lang.chat_template.get_chat_template_by_model_path(MODEL_PATH)取对话模板中的image_token拼进文本配合图片数据一并编码为input_ids从而将多模态输入也纳入 token 级工作流。结合源码的进一步探索如果想深入验证本文涉及的接口行为可以直接阅读仓库源码与测试引擎实现与参数解析位于 python/sglang/srt/server_args.pyServerArgs与add_cli_argssgl.Engine的上层封装在 python/sglang/lang/llm.py 附近continue_final_message、lora_path等 OpenAI 兼容请求参数的处理可在python/sglang/srt的入口与 HTTP 路由层搜索对应字段确认各类示例在 test/manual、test/registered 中均有对应回归测试可作为理解参数取值与边界的补充材料。整体来看examples/runtime目录是 SGLang 运行时能力最直观的活文档面向外部服务的 Native API 示例解决如何部署与调用离线 Engine 示例解决如何在进程内构建批处理与自定义服务Hidden States、Multimodal 与 Token-In-Token-Out 则覆盖嵌入提取、多模态理解与 RLHF 对齐等进阶工作流。读者可以按需挑选对应脚本以先起服务端、再跑客户端或直接运行 engine 脚本两种模式快速落地。【免费下载链接】sglangSGLang is a high-performance serving framework for large language models and multimodal models.项目地址: https://gitcode.com/GitHub_Trending/sg/sglang创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 SGLang Runtime 示例全解：从 Native API 到离线引擎的多场景推理实战
SGLang Runtime 示例全解从 Native API 到离线引擎的多场景推理实战【免费下载链接】sglangSGLang is a high-performance serving framework for large language models and multimodal models.项目地址: https://gitcode.com/GitHub_Trending/sg/sglang本指南以 SGLang 仓库中的 examples/runtime 目录为主线系统梳理 SGLang 运行时Runtime的各类官方示例OpenAI 兼容 Native API 下的 LoRA 微调适配、响应预填充response prefill、奖励模型打分与 Chain-of-Verification 幻觉抑制以及不依赖 HTTP 服务的离线 Engine API、Hidden States 提取、多模态推理和 Token-In-Token-Out 工作流。读完本文你将掌握如何在两个终端中分别启动 SGLang 服务端与运行客户端脚本并能按需组合 Engine API 打造自定义服务。使用前须知一切示例都基于服务端 客户端双终端模式examples/runtime下的绝大多数示例遵循同一套运行范式先在一个终端启动 SGLang 服务端再在另一个终端运行示例脚本。README 明确指出 The below examples will mostly need you to start a server in a separate terminal before you can execute them. Please see in the code for detailed instruction.大多数示例需要你先在单独的终端中启动服务器详细指令请参见代码中的注释。每个脚本的 docstring 头部都写明了对应的服务端启动命令例如# 以 LoRA 示例为例见 examples/runtime/lora.py python -m sglang.launch_server \ --model meta-llama/Llama-3.1-8B-Instruct \ --enable-lora \ --lora-paths sql/path/to/sql python/path/to/python服务端默认监听http://127.0.0.1:30000客户端脚本通过 OpenAI SDKopenai.Client(base_urlhttp://127.0.0.1:30000/v1)或直接requests.post访问/v1、/generate、/classify、/vertex_generate等路由。而engine子目录下的示例则属于离线引擎模式不经过 HTTP直接在 Python 进程内构造sgl.Engine完成推理特别适合批处理、离线评测与构建自定义服务。Native APIOpenAI 兼容接口下的七类典型用法1. LoRA 适配器模型参数中的adapter:name语法examples/runtime/lora.py 演示了在 OpenAI 兼容接口下使用 LoRA 适配器的完整流程。启动服务端时需额外传入两个参数--enable-lora开启 LoRA 支持--lora-paths sql/path/to/sql python/path/to/python以名称路径的键值对形式注册适配器。脚本覆盖四种请求形态import openai client openai.Client(base_urlhttp://127.0.0.1:30000/v1, api_keyEMPTY) # 1. Chat Completions通过 model 参数中的 adapter:name 语法指定适配器 response client.chat.completions.create( modelmeta-llama/Llama-3.1-8B-Instruct:sql, # ← adapter:name 语法 messages[{role: user, content: Convert to SQL: show all users}], max_tokens50, ) # 2. Completions API 同样支持适配器 response client.completions.create( modelmeta-llama/Llama-3.1-8B-Instruct:python, promptdef fibonacci(n):, max_tokens50, ) # 3. 向后兼容通过 extra_body 显式传入 lora_path response client.chat.completions.create( modelmeta-llama/Llama-3.1-8B-Instruct, messages[{role: user, content: Convert to SQL: show all users}], extra_body{lora_path: sql}, max_tokens50, ) # 4. 不携带任何适配器使用基础模型 response client.chat.completions.create( modelmeta-llama/Llama-3.1-8B-Instruct, messages[{role: user, content: Hello!}], max_tokens30, )其中modelbase_model:adapter_name的adapter:name语法是推荐的新式写法而extra_body{lora_path: sql}是向后兼容的旧式写法。若服务端未启动脚本会捕获异常并提示检查python -m sglang.launch_server --model ... --enable-lora --lora-paths ...。2. 多模态 Embedding/v1/embeddings路由examples/runtime/multimodal_embedding.py 演示了多模态嵌入提取。服务端以嵌入模式启动python -m sglang.launch_server --model-path Alibaba-NLP/gme-Qwen2-VL-2B-Instruct --is-embedding客户端通过原生 HTTP 构造input数组其中可混合文本与图片图片既支持 URL 也支持 base64 编码import requests url http://127.0.0.1:30000 text_input Represent this image in embedding space. image_path https://huggingface.co/datasets/liuhaotian/llava-bench-in-the-wild/resolve/main/images/023.jpg payload { model: gme-qwen2-vl, input: [{text: text_input}, {image: image_path}], } response requests.post(url /v1/embeddings, jsonpayload).json() print(Embeddings:, [x.get(embedding) for x in response.get(data, [])])这里的input列表即 OpenAI Embeddings API 的扩展形态每个元素用text或image字段区分模态。与离线引擎版的 examples/runtime/engine/embedding.py 相比后者通过sgl.Engine(model_path..., is_embeddingTrue)和llm.encode(prompts)实现网络版更适合部署后由外部服务调用。3. 批量请求Chat 与 CompletionsREADME 中还列有openai_batch_chat.py与openai_batch_complete.py两个示例分别演示如何用 OpenAI 兼容接口批量处理 Chat Completion 与文本 Completion 请求。两者均可借助 OpenAI SDK 在一个客户端会话中连续提交多条请求由 SGLang 服务端统一调度批处理是压测与批量评测的常用起点。4. 响应预填充continue_final_message参数examples/runtime/openai_chat_with_response_prefill.py 是 README 中重点加粗介绍的示例演示了 Anthropic 风格的 prefill Claudes response 技巧在 SGLang 中的实现启用continue_final_message后对话中最后一条不完整的assistant 消息会被移除其内容作为 prefill 喂给模型使模型续写这条消息而不是开启全新一轮。启动服务端后python -m sglang.launch_server --model-path meta-llama/Llama-3.1-8B-Instruct --port 30000运行脚本即可看到两种行为的对比import openai client openai.Client(base_urlhttp://127.0.0.1:30000/v1, api_keyEMPTY) messages [ {role: system, content: You are a helpful AI assistant.}, { role: user, content: Extract the name, size, price, and color from this product description as a JSON object: description The SmartHome Mini is a compact smart home assistant available in black or white for only $49.99. At just 5 inches wide, it lets you control lights, thermostats, and other connected devices via voice or app— no matter where you place it in your home. This affordable little hub brings convenient hands-free control to your smart devices. /description , }, {role: assistant, content: {\n}, # 预填充的 JSON 开头 ] # 启用 continue_final_messageassistant 消息被移除{\n 作为 prefill模型续写 JSON response_with client.chat.completions.create( modelmeta-llama/Llama-3.1-8B-Instruct, messagesmessages, temperature0, extra_body{continue_final_message: True}, ) print(response_with.choices[0].message.content) # 不启用保持默认行为模型会将其当作历史消息开启新的一轮 response_without client.chat.completions.create( modelmeta-llama/Llama-3.1-8B-Instruct, messagesmessages, temperature0, ) print(response_without.choices[0].message.content)该能力对结构化输出如强制 JSON 抽取尤其有用先由调用方写好{\n这类前缀让模型沿着既定格式续写显著提升格式命中率。5. 奖励模型打分/classify路由examples/runtime/reward_model.py 演示如何从奖励模型reward model中提取分数用于 RLHF 数据筛选等场景。服务端同样以嵌入模式启动python -m sglang.launch_server --model LxzGordon/URM-LLaMa-3.1-8B --is-embedding客户端向/classify路由提交conv字段——一个由多轮对话user/assistant 对组成的列表服务端为每段对话返回一个标量分数import requests url http://127.0.0.1:30000 PROMPT What is the range of the numeric output of a sigmoid node in a neural network? RESPONSE1 The output of a sigmoid node is bounded between -1 and 1. RESPONSE2 The output of a sigmoid node is bounded between 0 and 1. json_data { conv: [ [{role: user, content: PROMPT}, {role: assistant, content: RESPONSE1}], [{role: user, content: PROMPT}, {role: assistant, content: RESPONSE2}], ], } response requests.post(url /classify, jsonjson_data).json() print(scores:, [x[embedding] for x in response])返回结果中embedding字段承载奖励分数脚本会打印出两个候选回答各自的得分便于直观对比优劣上例中回答 2 才是正确的。6. Vertex AI 在线预测/vertex_generate路由examples/runtime/vertex_predict.py 展示了 Google Cloud Vertex AI Online Predictions 预测路由的请求/响应格式。它既可以在本地验证请求格式也提供了部署到 Vertex AI 后的 Python SDK 调用方式# 本地验证模拟 Vertex 的 instances/parameters 请求结构 import requests class LocalVertexEndpoint: def __init__(self) - None: self.base_url http://127.0.0.1:30000 def predict(self, instances, parametersNone): response requests.post( self.base_url /vertex_generate, json{instances: instances, parameters: parameters}, ) return VertexPrediction(predictionsresponse.json()[predictions]) # 单条提示词 response endpoint.predict(instances[{text: The capital of France is}]) # 多条提示词 采样参数 response endpoint.predict( instances[ {text: The capital of France is}, {text: What is a car?}, ], parameters{sampling_params: {max_new_tokens: 16}}, )脚本 docstring 同时给出了部署到 Vertex AI Endpoint 后通过 Python SDK 发送请求的写法response endpoint.predict( instances[{text: The capital of France is}, {text: What is a car?}], parameters{sampling_params: {max_new_tokens: 16}}, ) print(response.predictions)本地路由的关键在于把 SGLang 请求包装成 Vertex AI 的instancesparameters双层结构parameters.sampling_params内嵌 SGLang 采样参数实现从本地到云端的请求格式无缝迁移。7. Chain-of-VerificationCoVe用隔离会话抑制幻觉examples/runtime/chain_of_verification.py 实现了 Dhuliawala et al. (2023) 论文《Chain-of-Verification Reduces Hallucination in Large Language Models》中的Factored CoVe模式。其核心思想是验证环节在一个全新的、隔离的会话中执行不共享原始回答的任何历史与 KV-cache从而避免模型只是机械复述自己可能幻觉的回答而是真正去核查。这也正是 README 强调的 fresh, isolated session (no shared KV-cache) to avoid self-confirmation bias。完整流程分为四步步骤动作会话说明1. Draft起草将用户问题发送给模型得到初始回答独立会话2. Verify验证新开一个无历史的独立会话让模型扮演严格的事实核查者对问题 候选回答给出PASS或FAIL判定及理由全新会话无共享 KV-cache3. Refine修正若判定为 FAIL在验证会话内继续追问让模型基于批判上下文给出修正答案沿用验证会话4. Summarize可选将最终答案压缩为一段话新会话脚本提供完整的命令行参数--base-url默认http://127.0.0.1:30000/v1、--model缺省时自动从/v1/models探测、--prompt、--max-tokens、--temperature、--summarize、--quiet。例如python chain_of_verification.py --prompt What year did the Titanic sink? python chain_of_verification.py \ --base-url http://127.0.0.1:30002/v1 \ --model moonshot-v1-8k \ --prompt Who invented the telephone?实现上的一个细节值得注意脚本在提取模型输出时会同时检查content与reasoning_content字段——推理模型如 Kimi-K2.5、Qwen3在temperature0等配置下可能把正文放在reasoning_content中而content为空因此做了回退兜底。验证用的系统提示词为VERIFY_SYSTEM_PROMPT ( You are a strict fact-checker. You will be given a user question and a candidate answer. Decide whether the answer is accurate and directly addresses the question. Reply with exactly one of: PASS or FAIL, followed by a brief reason. )判定逻辑是verdict.strip().upper().startswith(PASS)即模型回复以PASS开头即视为通过验证否则进入修正环节。Engine 子目录离线引擎 API 全家桶examples/runtime/engine目录汇集了 Offline Engine API 的常见工作流示例对应的目录级说明文档为 examples/runtime/engine/readme.md。它的最大优势是无需 HTTP 服务器在进程内直接完成推理同时引擎会自动调度大批量请求以避免 OOM。启动引擎launch_engine.py与必须的__main__守卫最精简的引擎示例 examples/runtime/engine/launch_engine.pyimport sglang as sgl def main(): llm sgl.Engine(model_pathmeta-llama/Meta-Llama-3.1-8B-Instruct) llm.generate(What is the capital of France?) llm.shutdown() # 必须保留 __main__ 守卫 if __name__ __main__: main()代码注释明确解释了__main__条件的必要性SGLang 引擎使用spawn方式创建子进程spawn 每次都会启动一个全新的 Python 解释器如果缺少该守卫sgl.Engine会陷入无限循环地不断派生子进程。所有 Engine 示例含下方离线批处理、embedding、EAGLE、VLM 等都必须遵循这一约定。离线批处理offline_batch_inference.pyexamples/runtime/engine/offline_batch_inference.py 是批处理的标准模板通过ServerArgs.add_cli_args(parser)注入全部服务端命令行参数再以dataclasses.asdict(server_args)展开传给sgl.Engineimport argparse import dataclasses import sglang as sgl from sglang.srt.server_args import ServerArgs def main(server_args: ServerArgs): prompts [ Hello, my name is, The president of the United States is, The capital of France is, The future of AI is, ] sampling_params {temperature: 0.8, top_p: 0.95} llm sgl.Engine(**dataclasses.asdict(server_args)) outputs llm.generate(prompts, sampling_params) for prompt, output in zip(prompts, outputs): print() print(fPrompt: {prompt}\nGenerated text: {output[text]}) if __name__ __main__: parser argparse.ArgumentParser() ServerArgs.add_cli_args(parser) args parser.parse_args() server_args ServerArgs.from_cli_args(args) main(server_args)运行方式python3 offline_batch_inference.py --model meta-llama/Llama-3.1-8B-Instruct。当输入批次非常大时引擎会智能调度请求、高效处理并防止 OOM——这是离线引擎区别于逐个请求的关键收益。Embedding 生成examples/runtime/engine/embedding.py 展示了嵌入生成sgl.Engine(model_pathAlibaba-NLP/gte-Qwen2-1.5B-instruct, is_embeddingTrue)随后调用llm.encode(prompts)返回结果中的embedding字段即嵌入向量。与前面 Native API 的/v1/embeddings相比这里完全在进程内完成。EAGLE 投机解码examples/runtime/engine/offline_batch_inference_eagle.py 演示了基于 EAGLE 的投机解码speculative decoding。只需在构造 Engine 时指定一组投机解码参数llm sgl.Engine( model_pathmeta-llama/Llama-2-7b-chat-hf, speculative_algorithmEAGLE, speculative_draft_model_pathlmsys/sglang-EAGLE-llama2-chat-7B, speculative_num_steps3, speculative_eagle_topk4, speculative_num_draft_tokens16, cuda_graph_max_bs_decode8, ) outputs llm.generate(prompts, sampling_params)核心参数含义speculative_algorithm指定算法此处为 EAGLEspeculative_draft_model_path指向草稿模型speculative_num_steps为每轮推测步数speculative_eagle_topk为 EAGLE 每步保留的候选 token 数speculative_num_draft_tokens控制草稿 token 总量cuda_graph_max_bs_decode限定解码阶段 CUDA Graph 的最大批大小。VLM 推理examples/runtime/engine/offline_batch_inference_vlm.py 演示多模态模型离线推理。关键点是先从sglang.srt.parser.conversation的chat_templates中按chat_template参数取出对话模板用其image_token在提示词中占位再通过image_data传入图片 URLconv chat_templates[server_args.chat_template].copy() image_token conv.image_token image_url https://github.com/sgl-project/sglang/blob/main/examples/assets/example_image.png?rawtrue prompt fWhats in this image?\n{image_token} output vlm.generate( promptprompt, image_dataimage_url, sampling_params{temperature: 0.001, max_new_tokens: 30}, )运行python offline_batch_inference_vlm.py --model-path Qwen/Qwen2-VL-7B-Instruct。异步生成offline_batch_inference_async.pyexamples/runtime/engine/offline_batch_inference_async.py 展示异步生成用法engine.async_generate适用于在批处理框架上实现在线式请求既保留批量推理的吞吐又能以异步方式逐条响应。基于 Sanic 的自定义服务器custom_server.pyexamples/runtime/engine/custom_server.py 演示如何在 SGLang Engine 之上用 Sanic 搭建自定义服务同时提供非流式与流式两个端点。安装与运行步骤pip install sanic python custom_server # 仓库中实际运行命令为 python custom_server.pycurl -X POST http://localhost:8000/generate -H Content-Type: application/json -d {prompt: The Transformer architecture is...} curl -X POST http://localhost:8000/generate_stream -H Content-Type: application/json -d {prompt: The Transformer architecture is...} --no-buffer服务端实现的核心模式是复用引擎的异步接口from sanic import Sanic, text, json import sglang as sgl engine None app Sanic(sanic-server) app.route(/generate, methods[POST]) async def generate(request): prompt request.json.get(prompt) result await engine.async_generate(prompt) # async_generate 返回 dict return text(result[text]) app.route(/generate_stream, methods[POST]) async def generate_stream(request): prompt request.json.get(prompt) result await engine.async_generate(prompt, streamTrue) response await request.respond() async for chunk in result: # 流式结果是 async generator await response.send(chunk[text]) await response.eof() def run_server(): global engine engine sgl.Engine(model_pathmeta-llama/Meta-Llama-3.1-8B-Instruct) app.run(host0.0.0.0, port8000, single_processTrue)可见sgl.Engine.async_generate是构建自定义 Web 服务的统一异步入口非流式时返回 dict流式时返回 async generator。基于 FastAPI 的服务fastapi_engine_inference.pyexamples/runtime/engine/fastapi_engine_inference.py 展示如何用 FastAPI 的 lifespan 机制管理引擎生命周期。服务启动时初始化sgl.Engine请求通过engine.async_generate处理并支持MODEL_PATH/TP_SIZE环境变量配置python fastapi_engine_inference.py --model-path Qwen/Qwen2.5-0.5B-Instruct --tp_size 1 --host 127.0.0.1 --port 8000 [--startup-timeout 60]状态保存分片与远端 checkpoint该目录还包含两个模型状态保存示例save_sharded_state.py将每个 worker 的模型 state dict 直接保存为 checkpoint使大模型在张量并行tensor parallel场景下加载时每个 worker 只需读取自己的分片而非整个 checkpoint从而显著加速加载路径save_remote_state.py则将状态保存到远端存储--remote-model-save-url [protocol]://[host]:[port]/[model_name]。典型用法形如python save_sharded_state.py --model-path /path/to/load --quantization deepspeedfp --tensor-parallel-size 8 python save_remote_state.py --model-path /path/to/load --tensor-parallel-size 8 --remote-model-save-url [protocol]://[host]:[port]/[model_name]目录级说明文档examples/runtime/engine/readme.md 将上述能力归纳为五类使用场景Offline Batch Inference、Embedding Generation、Custom ServerSanic 示例、Token-In-Token-Out for RLHF、Inference Using FastAPI并指出引擎对超大批次会自动调度以避免 OOM。Hidden States提取隐藏状态的两条路径hidden_states目录见 examples/runtime/hidden_states提供隐藏状态提取示例。README 特别提醒该功能可能因 CUDA Graph 重建而降低吞吐因为服务端需要按配置的最大隐藏状态模式构建 CUDA Graph请求可以选择该模式或更弱的模式而不会触发按模式重捕图mode-dependent recapture。两条路径对应两个脚本Engine 路径hidden_states_engine.py构造引擎时传入return_hidden_states_modelast生成时在采样参数之外单独传return_hidden_stateslast结果从output[meta_info][hidden_states]取出并转为torch.bfloat16张量llm sgl.Engine( model_pathAlibaba-NLP/gte-Qwen2-1.5B-instruct, return_hidden_states_modelast, ) outputs llm.generate( prompts, sampling_paramssampling_params, return_hidden_stateslast, ) for prompt, output in zip(prompts, outputs): hidden_state torch.tensor(output[meta_info][hidden_states], dtypetorch.bfloat16) print(fPrompt: {prompt}\nGenerated text: {output[text]}\nLast hidden state: {hidden_state})Server 路径hidden_states_server.py以--return-hidden-states-mode last启动服务端然后向/generate提交请求并在请求体中携带return_hidden_states: last同样从响应meta_info.hidden_states中取回向量。脚本内部通过sglang.utils.launch_server_cmd自动拉起并回收服务进程可独立运行python hidden_states_server.py两条路径的关键参数保持一致服务端启动参数--return-hidden-states-mode决定 CUDA Graph 配置的最大模式请求级参数return_hidden_states决定本次请求实际提取的模式当前支持last即最后一层隐藏状态。Multimodal多模态输入的多模型示例multimodal目录见 examples/runtime/multimodal展示如何用 URL、本地文件或编码后的数据向多模态模型发起请求。README 概述了四类模型示例脚本模型支持能力llava_onevision_server.pyLlava-OneVisionlmms-lab/llava-onevision-qwen2-72b-ov图像、多图、视频qwen_llava_server.pyLlava-next 驱动的 Qwen-Llavalmms-lab/llava-next-72b图像、多图llama3_llava_server.pyLlava-next 驱动的 Llama3-Llavalmms-lab/llama3-llava-next-8b图像、多图pixtral_server.pyMistral Pixtralmistral-community/pixtral-12b图像、多图以 Llava-OneVision 为例服务端启动命令为python3 -m sglang.launch_server --model-path lmms-lab/llava-onevision-qwen2-72b-ov --port30000 --tp-size8 python3 llava_onevision_server.pyllava_onevision_server.py 内部较为完整包含四类测试图像流式请求OpenAI SDK 中以image_url类型携带 URLstreamTrue逐块输出多图流式请求多个image_url条目每个条目用modalities: multi-images标注配合一段文本提示模型描述两张图视频请求先用sglang.srt.utils.video_decoder.VideoDecoderWrapper解码视频用np.linspace均匀采样最多 32 帧逐帧转 JPEG 并 base64 编码以data:image/jpeg;base64,...形式 modalities: video组装进消息依赖pip install torchcodec与pip install protobuf3.20.0速度测试分别对图像与视频请求计时输出 Total / Completion / Prompt tokens 与每秒 token 数total_tokens / elapsed等。Token In, Token Out以 token 为边界的推理工作流token_in_token_out目录见 examples/runtime/token_in_token_out展示了 RLHF 等场景中常用的输入 token、输出 token工作流——调用方自行完成分词SGLang 只负责推理并返回生成的 token id全程绕开文本层。目录包含四个脚本覆盖 LLM/VLM × Engine/Server 四个组合token_in_token_out_llm_engine.pytoken_in_token_out_llm_server.pytoken_in_token_out_vlm_engine.pytoken_in_token_out_vlm_server.pyServer 版token_in_token_out_llm_server.py的关键在于服务端以--skip-tokenizer-init启动跳过分词器初始化随后向/generate提交input_idspython token_in_token_out_llm_server.py # 脚本内部自动启动服务端json_data { input_ids: token_ids_list, # 直接给 token id而非文本 sampling_params: sampling_params, } response requests.post(fhttp://localhost:{port}/generate, jsonjson_data)Engine 版token_in_token_out_llm_engine.py同样以sgl.Engine(model_pathMODEL_PATH, skip_tokenizer_initTrue)构造引擎用llm.generate(input_idstoken_ids_list, ...)推理。两个版本的输入都通过sglang.srt.utils.hf_transformers_utils.get_tokenizer(MODEL_PATH)获取 HuggingFace 分词器完成tokenizer.encode输出则读取output[output_ids]并用tokenizer.decode还原文本。VLM 版如token_in_token_out_vlm_server.py则引入图像 token 的处理通过sglang.lang.chat_template.get_chat_template_by_model_path(MODEL_PATH)取对话模板中的image_token拼进文本配合图片数据一并编码为input_ids从而将多模态输入也纳入 token 级工作流。结合源码的进一步探索如果想深入验证本文涉及的接口行为可以直接阅读仓库源码与测试引擎实现与参数解析位于 python/sglang/srt/server_args.pyServerArgs与add_cli_argssgl.Engine的上层封装在 python/sglang/lang/llm.py 附近continue_final_message、lora_path等 OpenAI 兼容请求参数的处理可在python/sglang/srt的入口与 HTTP 路由层搜索对应字段确认各类示例在 test/manual、test/registered 中均有对应回归测试可作为理解参数取值与边界的补充材料。整体来看examples/runtime目录是 SGLang 运行时能力最直观的活文档面向外部服务的 Native API 示例解决如何部署与调用离线 Engine 示例解决如何在进程内构建批处理与自定义服务Hidden States、Multimodal 与 Token-In-Token-Out 则覆盖嵌入提取、多模态理解与 RLHF 对齐等进阶工作流。读者可以按需挑选对应脚本以先起服务端、再跑客户端或直接运行 engine 脚本两种模式快速落地。【免费下载链接】sglangSGLang is a high-performance serving framework for large language models and multimodal models.项目地址: https://gitcode.com/GitHub_Trending/sg/sglang创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考