文章总结： 本文详细介绍了使用SGLang部署企业大模型API的完整流程，包括环境检查、镜像确认、最小启动、DockerCompose固化及逐层验证。核心结论是生产部署需关注稳定性、显存控制和回滚路径，而非仅启动命令。可操作建议包括固定镜像版本、使用健康检查和日志轮转，并强调以当前版本帮助为准调整参数。 综合评分： 88 文章分类： AI安全,安全建设,解决方案,安全工具,安全运营
SGLang 部署实战：快速启动企业大模型 API
点击关注 👉 点击关注 👉
马哥Linux运维
2026年7月17日 15:54 广东
在小说阅读器读本章
去阅读
SGLang 部署实战：快速启动企业大模型 API
大模型服务真正进入业务链路后，问题通常不再是“模型能不能回答”，而是服务能否稳定启动、显存是否可控、接口是否兼容、异常能否定位、升级能否回退。SGLang 提供 OpenAI 兼容接口、连续批处理、张量并行和多种推理优化，适合将本地模型目录快速变成企业内部 API；但生产部署不能只停留在一条启动命令，还需要把运行环境、配置固化、健康检查、权限边界和回滚路径一起设计好。
本文以 Linux、NVIDIA GPU、Docker Compose 和 SGLang 0.5.x 为主线。占位符统一写成 <变量名>：例如 <模型目录> 应替换为宿主机上的真实绝对路径，<镜像标签> 应替换为已经验证并固定的版本标签。SGLang 参数会随版本演进，执行前必须以当前镜像内 --help 的结果为准，不要直接把其他版本的参数复制到生产环境。
一、先确定部署边界
一个可维护的推理服务至少包含五层：模型文件、GPU 驱动与容器运行时、SGLang 进程、OpenAI 兼容 API、上游网关。SGLang 负责推理和请求调度，不负责企业级身份认证、TLS 证书、配额计费或跨节点流量治理，这些能力应由 Nginx、API Gateway 或服务网格承担。
上线前先确认以下参数，而不是边启动边猜：模型类型和精度、模型最大上下文、计划使用的 GPU 编号、张量并行度、单实例端口、允许访问的网段、预期并发、最大输入和输出长度。张量并行度通常等于单实例占用的 GPU 数量；显存利用率需要为 CUDA 上下文、通信缓冲区和运行时峰值留余量。
二、部署前检查主机与 GPU
先收集基础环境，不要在驱动不可用、磁盘不足或 GPU 已被占用的机器上直接拉起模型。下面的脚本只读，不会修改系统；它同时检查内核、容器引擎、磁盘和 GPU。
bash
#!/usr/bin/env bash
set -euo pipefail
MODEL_DIR="<模型目录>"
uname -a
docker version --format 'Server={{.Server.Version}}' 2>/dev/null || true
nvidia-smi --query-gpu=index,name,memory.total,memory.used,utilization.gpu \
--format=csv,noheader
df -h "${MODEL_DIR}"
du -sh "${MODEL_DIR}"
重点看三件事：nvidia-smi 能否正常返回、目标 GPU 是否有未知进程、模型所在文件系统是否还有足够空间。容器内使用 GPU 还依赖 NVIDIA Container Toolkit，宿主机能执行 nvidia-smi 并不等于容器一定能访问 GPU。
用最小 CUDA 容器验证运行时。<CUDA 镜像标签> 应替换为与当前驱动兼容、且企业镜像仓库已经缓存的标签。该命令只读取 GPU 信息，失败时应先修复容器运行时，不要继续排查 SGLang。
bash
docker run --rm --gpus all \
<CUDA镜像仓库>:<CUDA镜像标签> \
nvidia-smi
然后检查模型目录是否具备基本文件。不同架构文件名可能不同，但 Hugging Face 格式通常至少应包含配置、分词器和权重分片索引或权重文件。
bash
MODEL_DIR="<模型目录>"
test -r "${MODEL_DIR}/config.json"
find "${MODEL_DIR}" -maxdepth 1 -type f \
\( -name '*.safetensors' -o -name '*.safetensors.index.json' \
-o -name 'tokenizer.json' -o -name 'tokenizer_config.json' \) \
-printf '%f\n' | sort
若模型来自共享存储，还要观察实际读取速度和挂载类型。模型启动阶段长时间卡住并不一定是 GPU 问题，也可能是 CephFS、NFS 或对象存储网关吞吐不足。
bash
findmnt -T "<模型目录>" -o TARGET,SOURCE,FSTYPE,OPTIONS
iostat -xz 1 5
iostat 来自 sysstat 软件包。判断时关注模型盘的读吞吐、await 和 %util，不要仅凭“加载慢”就认定 SGLang 死锁。
三、确认镜像版本和真实参数
生产环境应固定镜像 digest 或明确版本标签，禁止长期使用 latest。先在目标镜像中查看版本、入口和帮助；帮助输出才是当前版本支持参数的证据。
bash
IMAGE="<SGLang镜像>:<镜像标签>"
docker image inspect "${IMAGE}" \
--format 'Id={{.Id}} Digests={{json .RepoDigests}}'
docker run --rm "${IMAGE}" python3 -m sglang.launch_server --help | less
需要重点确认 --model-path、--host、--port、--tp、--mem-fraction-static、--context-length 和 --served-model-name 是否存在。若帮助中的参数名不同，以帮助为准修改 Compose；不要同时保留新旧参数。
四、先用前台命令完成最小启动
第一次部署建议前台运行，让初始化错误直接显示。以下示例让单实例使用 GPU 0、1，张量并行度为 2，监听 8000。<对外模型名> 是客户端请求中使用的逻辑名称，不必与目录名相同。
bash
docker run --rm --gpus '"device=0,1"' \
--ipc=host \
--shm-size=32g \
-p 8000:8000 \
-v "<模型目录>:/models/model:ro" \
<SGLang镜像>:<镜像标签> \
python3 -m sglang.launch_server \
--model-path /models/model \
--served-model-name <对外模型名> \
--host 0.0.0.0 \
--port 8000 \
--tp 2 \
--context-length 8192 \
--mem-fraction-static 0.85
--ipc=host 和较大的共享内存可避免多进程通信受容器默认 /dev/shm 限制。--mem-fraction-static 0.85 不是“最多只用 85% 总显存”的绝对承诺，而是影响 SGLang 静态内存池规划；值越高，可用于 KV Cache 的空间通常越大，但启动或峰值阶段更容易 OOM。应从保守值开始，以真实上下文长度和并发压测验证。
如果模型代码确实要求远程自定义实现，当前版本帮助中支持时才加 --trust-remote-code。该选项会执行模型仓库内的 Python 代码，必须先完成代码审查；不要把它作为加载失败的通用修复。
五、使用 Docker Compose 固化实例
前台启动验证通过后，再将参数固化。下面是一份相对完整的 Compose 配置，使用显式 GPU 设备映射、只读模型挂载、健康检查和日志轮转。Compose 的 GPU 语法取决于 Docker Compose 版本，因此部署前先执行 docker compose version 和 docker compose config。
yaml
services:
sglang-api:
image:<SGLang镜像>:<镜像标签>
container_name:sglang_api_8000
restart:unless-stopped
ipc:host
shm_size:32g
ports:
-"8000:8000"
environment:
CUDA_VISIBLE_DEVICES:"0,1"
volumes:
-<模型目录>:/models/model:ro
deploy:
resources:
reservations:
devices:
-driver:nvidia
device_ids: ["0", "1"]
capabilities: [gpu]
command:
-python3
--m
-sglang.launch_server
---model-path
-/models/model
---served-model-name
-<对外模型名>
---host
-0.0.0.0
---port
-"8000"
---tp
-"2"
---context-length
-"8192"
---mem-fraction-static
-"0.85"
healthcheck:
test: ["CMD-SHELL", "python3 -c \"import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/health', timeout=3)\""]
interval:30s
timeout:5s
retries:5
start_period:600s
logging:
driver:json-file
options:
max-size:100m
max-file:"5"
start_period 要覆盖实际模型加载时间，否则容器在初始化阶段会持续显示不健康。健康检查路径需要以当前 SGLang 版本为准；如果该版本没有 /health，可改用已确认存在的只读模型列表接口，但不要用会触发推理的长请求做高频健康检查。
启动前先渲染配置，检查占位符是否全部替换、端口和 GPU 是否冲突。
bash
COMPOSE_FILE="<Compose文件路径>"
docker compose -f "${COMPOSE_FILE}" config
docker ps --format '{{.Names}}\t{{.Ports}}' | grep -E '8000|sglang' || true
nvidia-smi --query-compute-apps=gpu_uuid,pid,used_memory \
--format=csv,noheader || true
确认无误后启动，并只查看这个服务的状态。Compose 子命令使用的是 service 名 sglang-api，不是 container_name。
bash
docker compose -f <Compose文件路径> up -d sglang-api
docker compose -f <Compose文件路径> ps sglang-api
docker compose -f <Compose文件路径> logs -f --tail=200 sglang-api
六、从端口、健康到推理逐层验证
先验证进程是否监听，以及 HTTP 健康检查能否返回。端口监听正常只能说明进程已经绑定 socket，不能证明模型推理成功。
bash
ss -lntp | grep ':8000 '
curl --fail --silent --show-error \
--connect-timeout 3 --max-time 10 \
http://127.0.0.1:8000/health
再检查 OpenAI 兼容的模型列表，确认 <对外模型名> 与启动参数一致。
bash
curl --fail --silent --show-error \
http://127.0.0.1:8000/v1/models | jq .
完成一次非流式对话验证。这里的 max_tokens 是最大生成 token 数，不是整个上下文长度；输入和输出总量仍受服务端上下文限制。
bash
curl --fail --silent --show-error \
http://127.0.0.1:8000/v1/chat/completions \
-H 'Content-Type: application/json' \
-d '{
"model": "<对外模型名>",
"messages": [
{"role": "system", "content": "你是企业内部运维助手。"},
{"role": "user", "content": "只回复：ready"}
],
"temperature": 0,
"max_tokens": 16,
"stream": false
}' | jq .
流式接口需要确认响应是逐段到达，而不是被中间代理缓存。curl -N 关闭客户端输出缓冲，便于观察 SSE 数据。
bash
curl -N --fail --silent --show-error \
http://127.0.0.1:8000/v1/chat/completions \
-H 'Content-Type: application/json' \
-d '{
"model": "<对外模型名>",
"messages": [{"role": "user", "content": "列出三项上线检查。"}],
"temperature": 0.2,
"max_tokens": 128,
"stream": true
}'
业务通常通过 OpenAI SDK 调用。不同 SDK 版本的初始化参数可能变化，下面适用于支持 base_url 的 OpenAI Python SDK；API Key 由网关校验时应从安全环境变量读取，而不是写进代码仓库。
python
import os
from openai import OpenAI
client = OpenAI(
base_url=os.environ.get("LLM_BASE_URL", "http://127.0.0.1:8000/v1"),
api_key=os.environ.get("LLM_API_KEY", "local-not-checked"),
)
response = client.chat.completions.create(
model="<对外模型名>",
messages=[{"role": "user", "content": "返回当前请求是否成功。"}],
temperature=0,
max_tokens=64,
)
print(response.choices[0].message.content)
不要只看 HTTP 200。验收至少要核对：响应 JSON 结构、模型名称、结束原因、首 token 是否及时、长输入是否被正确拒绝、客户端主动断开后服务端是否释放请求。
七、配置基线压测，而不是追求一个漂亮数字
压测的目标是找到并发、上下文和输出长度变化下的稳定边界。测试数据不能包含生产隐私，结果也不能跨模型、精度和硬件直接比较。下面脚本并发发送固定短请求，记录每个请求的 HTTP 状态与总耗时；它适合连通性和粗粒度稳定性检查，不替代专业推理基准工具。
bash
#!/usr/bin/env bash
set -euo pipefail
URL="${URL:-http://127.0.0.1:8000/v1/chat/completions}"
MODEL="${MODEL:-<对外模型名>}"
CONCURRENCY="${CONCURRENCY:-8}"
TOTAL="${TOTAL:-32}"
TMP_DIR="$(mktemp -d)"
trap'rm -rf "${TMP_DIR}"' EXIT
request_one() {
localid="$1"
curl -sS -o "${TMP_DIR}/${id}.json" \
-w "id=${id} code=%{http_code} total=%{time_total}\n" \
-H 'Content-Type: application/json' \
-d "{\"model\":\"${MODEL}\",\"messages\":[{\"role\":\"user\",\"content\":\"返回编号 ${id}\"}],\"max_tokens\":32,\"temperature\":0}" \
"${URL}"
}
export -f request_one
export URL MODEL TMP_DIR
seq 1 "${TOTAL}" | xargs -P "${CONCURRENCY}" -I{} bash -c 'request_one "$@"' _ {}
执行时同时采集 GPU 利用率和显存。若吞吐不再上升但排队时延持续增加，说明实例已越过经济并发点；此时通常应限流或增加实例，而不是继续把并发调大。
bash
nvidia-smi dmon -s pucvmet -d 1 -o DT
dmon 字段随驱动和 GPU 型号略有差异。重点观察 SM 利用率、显存占用、功耗和温度是否持续异常；GPU 利用率高本身不是故障，只有与超时、错误率、降频或队列增长结合才有诊断意义。
八、启动失败的证据链
1. 容器立即退出
先看退出码、错误日志和容器实际参数，不要反复 restart 掩盖首个错误。
bash
CONTAINER="sglang_api_8000"
docker inspect "${CONTAINER}" \
--format 'Status={{.State.Status}} Exit={{.State.ExitCode}} Error={{.State.Error}} OOM={{.State.OOMKilled}}'
docker logs --timestamps --tail=300 "${CONTAINER}"
docker inspect "${CONTAINER}" --format '{{json .Config.Cmd}}' | jq .
退出码 137 可能来自 OOM Kill 或外部强制终止，必须结合 .State.OOMKilled、内核日志和 GPU 日志判断，不能只凭退出码下结论。
2. CUDA OOM 或静态内存池分配失败
先确认目标 GPU 上的全部计算进程以及容器映射。发现未知 PID 时应定位归属，不要直接杀进程。
bash
nvidia-smi --query-gpu=index,uuid,memory.total,memory.used,memory.free \
--format=csv
nvidia-smi --query-compute-apps=gpu_uuid,pid,process_name,used_memory \
--format=csv
docker inspect sglang_api_8000 \
--format '{{json .HostConfig.DeviceRequests}}' | jq .
有证据表明显存不足后，按风险从低到高处理：降低 --mem-fraction-static、缩短 --context-length、减少同卡其他进程、增加张量并行 GPU 数；更改并行度会改变资源拓扑和性能，必须重新压测。不要在未确认原因时设置 PyTorch 内存环境变量碰运气。
3. 多卡初始化卡住
检查每张卡是否属于同一实例、NVLink/PCIe 拓扑是否符合预期，再查看进程和网络端口。多卡 100% 利用率并不必然代表正在有效推理，也可能是通信重试或内核卡住。
bash
nvidia-smi topo -m
ps -eo pid,ppid,stat,etime,cmd | grep -E '[s]glang|[t]orch'
ss -lntp | grep -E ':8000|torch|python' || true
如需进一步确认 GPU 错误，可查看内核日志。dmesg 可能需要相应权限；重点检索 NVRM Xid、PCIe 和 OOM 证据。
bash
journalctl -k --since '-30 min' --no-pager \
| grep -Ei 'NVRM|Xid|oom|pcie|nvlink' || true
4. 服务可访问但请求超时
先把客户端 DNS、TCP 建连、首字节和总耗时拆开。若直连本机快、经过网关慢，问题在代理链路的概率高；若直连也慢，再结合请求长度、排队和 GPU 指标定位。
bash
curl -sS -o /dev/null \
-w 'dns=%{time_namelookup} connect=%{time_connect} start=%{time_starttransfer} total=%{time_total} code=%{http_code}\n' \
--max-time 120 \
http://127.0.0.1:8000/v1/models
访问日志中应记录请求 ID、状态码和耗时，但不要记录完整提示词或模型输出。提示词可能包含客户数据、凭据和个人信息，默认应视为敏感数据。
九、限制暴露面与保护 API
若 SGLang 只由同机 Nginx 访问，优先绑定 127.0.0.1；跨主机访问则通过内网地址、安全组或防火墙限制来源。SGLang 端口不应直接暴露到互联网。认证、TLS、请求体大小、并发限制和审计应放在网关层。
服务账号只需要读取模型目录，不应拥有模型文件写权限。可以用以下命令检查挂载和容器权限边界。
bash
docker inspect sglang_api_8000 \
--format '{{range .Mounts}}{{println .Source "->" .Destination "RW=" .RW}}{{end}}'
docker exec sglang_api_8000 sh -c \
'id; test -r /models/model/config.json; test ! -w /models/model/config.json'
企业 API 还应设置请求体上限和生成上限。仅限制 HTTP 请求大小不能限制 token 消耗；应在网关、业务层和推理参数三处协同约束。对外返回错误时隐藏宿主机模型路径、栈跟踪和内部 IP。
十、升级、灰度和回滚
升级前先记录旧镜像 digest、完整 Compose 配置、模型配置和基线请求。模型权重通常只读，不需要复制一份；但自定义聊天模板、网关配置和启动文件必须纳入版本控制。
bash
#!/usr/bin/env bash
set -euo pipefail
COMPOSE_FILE="<Compose文件路径>"
BACKUP_DIR="<备份目录>/sglang-$(date +%Y%m%d-%H%M%S)"
mkdir -p "${BACKUP_DIR}"
cp -a "${COMPOSE_FILE}" "${BACKUP_DIR}/"
docker compose -f "${COMPOSE_FILE}" config > "${BACKUP_DIR}/compose.rendered.yaml"
docker image inspect <SGLang镜像>:<旧镜像标签> > "${BACKUP_DIR}/image.inspect.json"
sha256sum <模型目录>/config.json > "${BACKUP_DIR}/model-config.sha256"
printf '%s\n' "Backup: ${BACKUP_DIR}"
推荐在新端口启动新版本，例如 8001，完成健康检查、短请求、长上下文、流式输出和小流量灰度后，再切换网关。这样旧实例仍可承接流量，回滚只需把上游指回旧端口。
切换前执行配置检查，切换后同时验证新实例与用户入口。以下只是连续操作范例，<网关配置文件> 和测试 URL 必须替换为实际值。
bash
sudo cp -a <网关配置文件> <网关配置文件>.bak.$(date +%Y%m%d-%H%M%S)
sudo nginx -t
sudo systemctl reload nginx
curl -fsS http://127.0.0.1:8001/health
curl -fsS https://<企业API域名>/v1/models | jq .
如果错误率、首 token 时延或输出一致性不符合基线，先回切网关，再停止新实例。停止容器会中断该实例上的在途请求，应先从负载均衡摘除并等待连接排空。
bash
sudo cp -a <网关配置文件>.bak.<时间戳> <网关配置文件>
sudo nginx -t && sudo systemctl reload nginx
docker compose -f <新版本Compose文件> stop sglang-api
curl -fsS https://<企业API域名>/v1/models | jq .
回滚完成的判断不是“旧容器启动了”，而是入口恢复、核心请求成功、错误率回落、旧模型名与聊天模板正确。新版本日志和失败请求 ID 应保留，用于离线复盘。
十一、日常巡检脚本
下面脚本适合由监控系统或低频定时任务执行。它检查容器状态、健康接口、模型列表和 GPU 基础状态，不触发生成请求，避免巡检本身占用大量推理资源。
bash
#!/usr/bin/env bash
set -euo pipefail
CONTAINER="${CONTAINER:-sglang_api_8000}"
BASE_URL="${BASE_URL:-http://127.0.0.1:8000}"
EXPECTED_MODEL="${EXPECTED_MODEL:-<对外模型名>}"
status="$(docker inspect -f '{{.State.Status}}' "${CONTAINER}")"
[[ "${status}" == "running" ]] || {
echo"CRITICAL: container status=${status}" >&2
exit 2
}
curl -fsS --max-time 5 "${BASE_URL}/health" >/dev/null
models="$(curl -fsS --max-time 10 "${BASE_URL}/v1/models")"
jq -e --arg model "${EXPECTED_MODEL}" \
'.data[] | select(.id == $model)' <<<"${models}" >/dev/null
nvidia-smi --query-gpu=index,memory.used,memory.total,utilization.gpu,temperature.gpu \
--format=csv,noheader
echo"OK: ${CONTAINER} model=${EXPECTED_MODEL}"
脚本返回非零只说明巡检条件不满足，自动重启前仍应区分初始化过慢、模型接口异常、GPU Xid、上游拥塞和人为变更。对大模型服务而言，盲目重启可能丢失现场、加剧模型重复加载并中断更多请求。
十二、上线验收清单
最终验收应形成可追溯记录：镜像版本和 digest 已固定；模型目录只读；GPU 编号与 TP 一致；帮助确认过所有启动参数；健康、模型列表、非流式和流式请求均通过；长上下文和超限请求行为符合预期；压测覆盖目标并发；日志不泄露提示词；SGLang 端口未直接暴露公网；网关具备认证、TLS、限流和超时；升级采用新端口灰度；旧镜像、旧配置和回切步骤仍可用。
部署是否成功，不应只看容器处于 Up。真正的完成标准是：服务从基础设施到业务入口都能验证，异常有证据可查，资源边界可控，任何一次配置或版本变更都有明确回滚路径。
文末阅读福利
仅目前来说，无论是运维人转型提升，还是零基础想转行IT，最好的岗位就是云计算运维&SRE岗位。
为了帮助大家早日快速入门云计算运维领域，给大家整理了一套【最新运维资料】高级运维工程师必备技能资料包（文末一键免费领取），内容有多详实丰富看下图！
1.38张最全工程师技能图谱
2.面试大礼包
3.Linux书籍
内容比较多，就不一一展示了
以上所有资料获取请扫码：
识别上方二维码
备注：2026最新运维资料
100%免费领取
（是扫码领取，不是在公众号后台回复，别看错了哦）
免责声明：
本文所载程序、技术方法仅面向合法合规的安全研究与教学场景，旨在提升网络安全防护能力，具有明确的技术研究属性。
任何单位或个人未经授权，将本文内容用于攻击、破坏等非法用途的，由此引发的全部法律责任、民事赔偿及连带责任，均由行为人独立承担，本站不承担任何连带责任。
本站内容均为技术交流与知识分享目的发布，若存在版权侵权或其他异议，请通过邮件联系处理，具体联系方式可点击页面上方的联系我。
本文转载自：马哥Linux运维 点击关注 👉 点击关注 👉《SGLang 部署实战：快速启动企业大模型 API》
版权声明
本站仅做备份收录，仅供研究与教学参考之用。
读者将信息用于其他用途的，全部法律及连带责任由读者自行承担，本站不承担任何责任。
评论