核心内容摘要
Chandra OCR惊艳案例：扫描版《微积分》教材PDF→Markdown，公式LaTeX无损导出
SGLang服务启动命令详解参数不再难懂你是否在启动SGLang服务时面对python3 -m sglang.launch_server后面一长串参数感到困惑——--model-path到底填什么路径--host
0.
0.
0和
127.
0.
1有什么区别--log-level warning调成info会炸屏吗为什么加了--tp 2反而报错别急这不是你的问题而是官方文档没把“人话”写清楚。
作为已用SGLang部署过12个不同尺寸模型从Phi-3到Qwen
B的实践者我决定把所有踩过的坑、验证过的组合、真正影响性能的关键参数用一句句大白话讲明白。
不堆术语不绕概念只告诉你每个参数是什么、不设它会怎样、设错了会出什么问题、什么场景下必须改它。
读完本文你将能看懂任意一条SGLang启动命令的真实含义根据显卡数量、模型大小、并发需求快速写出最合适的启动命令避开90%新手必踩的路径错误、端口冲突、权限异常理解--mem-fraction-static这类“隐形杀手”参数的实际作用掌握服务健康检查与日志定位的实用技巧
启动命令全貌从一行命令拆解出6个关键模块
1 命令结构图解先建立整体认知SGLang服务启动命令看似复杂其实就6个逻辑模块按执行顺序排列如下python3 -m sglang.launch_server \ --model-path /path/to/model \ # 【核心】告诉它模型在哪 --host
0.
0.
0 \ # 【网络】谁可以访问这台服务 --port 30000 \ # 【网络】用哪个门牌号收发请求 --tp 2 \ # 【算力】用几块GPU并行跑 --mem-fraction-static
8 \ # 【内存】给KV缓存留多少显存 --log-level warning # 【调试】让它少说点废话还是多吐点线索重要提醒--model-path是唯一强制参数其他全可省略——但省略≠推荐。
默认值往往只适合单卡小模型生产环境必须显式配置。
2 每个参数的“人话翻译”与真实影响参数官方描述精简人话解释不设会怎样设错典型后果实战建议--model-path模型权重路径必须指向包含config.json、pytorch_model.bin或model.safetensors的文件夹启动直接报错FileNotFoundError: config.json not found路径末尾多一个/、用相对路径未从正确目录执行、路径含中文或空格 → 全部失败用绝对路径 进入模型目录后执行pwd复制路径 启动前ls -l确认config.json存在--host绑定IP地址决定服务“开哪扇门”
127.
0.
1只允许本机访问
0.
0.
0允许局域网所有设备访问默认
127.
0.
1远程机器curl会返回Connection refused设成
0.
0.
0却没配防火墙 → 局域网内任何人可调用你的大模型API开发调试用
127.
0.
1部署到服务器且需远程调用设
0.
0.
0并配防火墙规则--port绑定端口号就像快递柜的格子号客户端必须用这个数字找服务默认30000若该端口被占用如另一个SGLang实例、MySQL启动失败报Address already in use设成80或443却没root权限 → 启动报Permission denied 优先选
区间启动前用lsof -i :30000查端口占用--tpTensor Parallelism张量并行GPU数把一个大模型“切片”分给多块GPU同时算。
--tp 2用2块GPU跑同一个模型默认1单卡运行。
模型太大显存不够时会OOM崩溃--tp 2却只插了1块GPU → 启动报CUDA error: invalid device ordinal--tp 3配3卡但其中1卡被占用 → 启动卡死查GPUnvidia-smi -L 确保--tp值 ≤ 可用GPU数 多卡时用CUDA_VISIBLE_DEVICES0,1 python3 -m ... --tp 2显式指定--mem-fraction-staticKV缓存静态显存占比控制“记忆空间”大小。
SGLang用RadixAttention共享KV缓存此值决定给共享缓存预留多少显存默认
880%显存对7B模型够用但跑Qwen
B时80%可能不够导致请求中途OOM设太高如
95→ 其他计算没显存吞吐暴跌设太低如
3→ 缓存命中率骤降延迟翻倍⚖ 7B模型
7-
813B
75-
8572B
85-
92实测用nvidia-smi观察Memory-Usage动态调整--log-level日志级别控制控制台输出多少信息warning只报错info报关键步骤debug每一步都记默认warning启动成功后几乎不输出你不知道它到底跑没跑起来debug模式下每秒刷几百行日志终端卡死且日志文件暴涨 启动时用info看加载进度线上服务用warning排障时临时切debug
实战命令模板覆盖95%使用场景
1 单卡开发调试最常用python3 -m sglang.launch_server \ --model-path /home/user/models/Qwen
B-Instruct \ --host
127.
0.
1 \ --port 30000 \ --log-level info为什么这样配
127.
0.
1确保只有本机你的Jupyter/Postman能调用安全--log-level info让你看到“Loading model...”、“Tokenizer loaded”、“Server started”三步关键日志确认真跑起来了不加--tp默认单卡避免误触发多卡逻辑。
2 双卡高性能服务推荐生产环境python3 -m sglang.launch_server \ --model-path /home/user/models/Qwen
B-Instruct \ --host
0.
0.
0 \ --port 30000 \ --tp 2 \ --mem-fraction-static
82 \ --log-level warning关键点解析--tp 2明确告诉SGLang用2块GPU并行计算吞吐量接近单卡2倍--mem-fraction-static
8213B模型需要更多KV缓存空间82%比默认80%更稳妥--log-level warning线上服务不刷屏出错才报警。
3 大模型72B级四卡部署避坑重点CUDA_VISIBLE_DEVICES0,1,2,3 python3 -m sglang.launch_server \ --model-path /home/user/models/Qwen
B-Instruct \ --host
0.
0.
0 \ --port 30000 \ --tp 4 \ --mem-fraction-static
9 \ --log-level warning必须加CUDA_VISIBLE_DEVICES的原因SGLang的--tp参数只负责逻辑切分不负责物理GPU选择。
如果你机器有8块卡但只想用
号必须用CUDA_VISIBLE_DEVICES屏蔽掉
号否则SGLang可能错误调度到被占用的卡上导致OOM或静默失败。
常见故障排查5分钟定位90%启动失败原因
1 启动卡住不动检查这3个地方现象命令执行后光标一直闪烁无任何输出CtrlC也无效90%原因--model-path路径错误SGLang在默默尝试加载不存在的文件超时等待解决立即CtrlC中断进入模型目录执行ls -l config.json pytorch_model.bin确认文件存在用pwd复制绝对路径替换命令中的--model-path。
2 报错OSError: CUDA out of memory不是显存不够是配错了真相--mem-fraction-static设太低KV缓存空间不足SGLang被迫频繁申请释放显存引发碎片化OOM验证方法启动时加--log-level debug观察日志中是否有kv cache size相关警告同时开另一个终端运行watch -n 1 nvidia-smi看显存占用是否在95%附近剧烈波动。
解决逐步提高--mem-fraction-static每次
02直到波动消失。
3 curl localhost:30000/v1/models 返回404服务根本没起来误区以为端口通了服务就在真相SGLang启动成功后会打印INFO: Uvicorn running on http://
0.
0.
0:30000没有这行服务就没活排查链检查--log-level是否设成了warning成功日志是INFO级会被过滤→ 临时改成info检查--host是否设为
127.
0.
1而你用curl
0.
0.
0:30000→ 改成一致检查防火墙sudo ufw status若为active执行sudo ufw allow 30000。
进阶技巧让服务更稳、更快、更省
1 用systemd守护进程告别SSH断连服务挂创建/etc/systemd/system/sglang-qwen13b.service[Unit] DescriptionSGLang Qwen
B Service Afternetwork.target [Service] Typesimple Userubuntu WorkingDirectory/home/ubuntu ExecStart/usr/bin/python3 -m sglang.launch_server \ --model-path /home/ubuntu/models/Qwen
B-Instruct \ --host
0.
0.
0 \ --port 30000 \ --tp 2 \ --mem-fraction-static
82 \ --log-level warning Restartalways RestartSec10 StandardOutputjournal StandardErrorjournal [Install] WantedBymulti-user.target启用sudo systemctl daemon-reload sudo systemctl enable sglang-qwen13b.service sudo systemctl start sglang-qwen13b.service # 查看日志sudo journalctl -u sglang-qwen13b.service -f
2 监控显存与请求延迟一目了然SGLang内置Prometheus指标启动时加--enable-metricspython3 -m sglang.launch_server \ --model-path /path/to/model \ --enable-metrics \ ...然后访问http://localhost:30000/metrics你会看到sglang_gpu_cache_usage_ratioKV缓存实际使用率理想值
7-
9sglang_request_latency_secondsP95请求延迟单位秒sglang_num_requests_running当前处理请求数用Grafana接入5分钟搭好监控面板。
3 批量启动多个模型端口规划指南想同时跑Qwen
B和Qwen
B别用同一端口推荐端口规划模型端口用途Qwen
B30000默认开发端口Qwen
B30001主力服务端口Phi-3-mini30002轻量测试端口Llama
B30003多模态实验端口启动命令只需改--port其他参数复用管理清晰不混乱。
5.
总结与行动清单SGLang启动参数不是玄学而是可预测、可验证、可优化的工程配置。
核心就三点路径是命脉--model-path必须绝对路径文件存在这是启动成功的前提资源要匹配--tp值必须≤可用GPU数--mem-fraction-static要根据模型大小动态调优网络要清醒--host决定谁能访问--port决定走哪扇门两者配合才能让服务真正可用。
现在打开你的终端执行这三步立刻验证运行python3 -c import sglang; print(sglang.__version__)确认SGLang v
0.
6已正确安装马上测试用
1节的单卡命令启动一个Qwen
B然后curl http://
127.
0.
1:30000/v1/models看到JSON响应即成功持续优化启动后用nvidia-smi观察显存用curl压测并发根据sglang_gpu_cache_usage_ratio微调--mem-fraction-static。
参数不再难懂是因为你已掌握它的逻辑。
真正的难点从来不在命令行而在理解模型、硬件与业务需求之间的平衡。