简介:本文按资源规划、启动配置、健康检查、网关接入、压测记录、回滚和故障排查的顺序,给出可替换参数的启动脚本、systemd 配置、检查脚本和上线检查表。团队照着做,能减少上线后的反复调试,出现问题时也能快速定位并安全回退。
本文以 vLLM 提供的 OpenAI 兼容接口为例。其他推理框架的思路相同,只需把参数名替换成对应框架文档中的写法。模型能力、许可证和适用范围不在本文讨论范围内,这些内容以模型卡、许可证和团队自己的评测结果为准。
命令中的版本号、路径和域名都是占位内容,执行前需要替换成团队的实际值。
上线前逐项确认以下内容,全部打勾后再切换流量。
/v1/models 能列出目标模型。推理进程只监听 127.0.0.1:8000,外部流量只能经过网关访问。网关监听 443 端口,负责证书、认证、限流和超时。
测试环境可以只部署一个副本。生产环境至少部署两个副本,放在不同机器上,前面接负载均衡。
模型权重按版本存放,例如 /data/models/your-model/v1。权重目录设为只读,升级时新建目录,不覆盖旧版本。
把参数和密钥放进环境文件,权限设为 600,只允许服务账号读取。
# /etc/vllm/vllm.envVLLM_API_KEY=替换为从密钥管理系统注入的值MODEL_PATH=/data/models/your-model/v1SERVED_NAME=mm-modelHOST=127.0.0.1PORT=8000MAX_MODEL_LEN=8192GPU_MEM_UTIL=0.90MAX_NUM_SEQS=8TP_SIZE=1MM_LIMIT={"image": 2}
API Key 通过 VLLM_API_KEY 环境变量读取,不放在命令行参数里。命令行参数会被 ps 等工具看到,存在泄露风险。
启动脚本 /opt/vllm/start.sh 如下。
#!/usr/bin/env bashset -euo pipefail: "${MODEL_PATH:?MODEL_PATH 未设置}": "${SERVED_NAME:?SERVED_NAME 未设置}"exec vllm serve "$MODEL_PATH" \--served-model-name "$SERVED_NAME" \--host "$HOST" --port "$PORT" \--max-model-len "$MAX_MODEL_LEN" \--gpu-memory-utilization "$GPU_MEM_UTIL" \--max-num-seqs "$MAX_NUM_SEQS" \--tensor-parallel-size "$TP_SIZE" \--limit-mm-per-prompt "$MM_LIMIT"
exec 让 vLLM 替换启动脚本的进程,systemd 才能直接管理它。--limit-mm-per-prompt 的写法随 vLLM 版本变化,以所用版本的文档为准。模型要求 --trust-remote-code 时才加这个参数,并先确认代码来源可信。
systemd 配置 /etc/systemd/system/vllm.service 如下。
[Unit]Description=vLLM multimodal inferenceAfter=network-online.targetWants=network-online.targetStartLimitIntervalSec=600StartLimitBurst=5[Service]User=vllmGroup=vllmEnvironmentFile=/etc/vllm/vllm.envExecStart=/opt/vllm/start.shRestart=on-failureRestartSec=10TimeoutStartSec=900LimitNOFILE=65535[Install]WantedBy=multi-user.target
TimeoutStartSec 设为 900 秒,给大模型加载留出时间。StartLimitBurst 限制短时间内的重启次数,避免配置错误时无限重启。
启动和查看日志的命令如下。
sudo systemctl daemon-reloadsudo systemctl enable --now vllmsudo systemctl status vllmjournalctl -u vllm -f
进程启动成功不等于服务可用。模型加载需要时间,加载期间接口可能无法返回结果。
检查分三层。第一层确认 HTTP 服务存活,第二层确认模型已注册可用,第三层确认图文请求能返回结果。
#!/usr/bin/env bashset -euo pipefailsource /etc/vllm/vllm.env# 存活检查:HTTP 服务是否响应curl -fsS -m 5 http://127.0.0.1:8000/health >/dev/null# 就绪检查:模型是否已注册curl -fsS -m 5 -H "Authorization: Bearer ${VLLM_API_KEY}" \http://127.0.0.1:8000/v1/models | grep -q "${SERVED_NAME}"echo "health check passed"
图文请求用于验证完整链路。图片地址需要能被推理机访问。
curl -fsS http://127.0.0.1:8000/v1/chat/completions \-H "Authorization: Bearer ${VLLM_API_KEY}" \-H "Content-Type: application/json" \-d '{"model": "mm-model","messages": [{"role": "user", "content": [{"type": "text", "text": "用一句话描述这张图"},{"type": "image_url", "image_url": {"url": "https://example.com/test.jpg"}}]}],"max_tokens": 64}'
vLLM 通过 /metrics 暴露 Prometheus 指标。监控需要采集 GPU 显存、排队请求数和请求延迟,并为排队数和错误率设置告警。
网关负责 TLS、认证、限流和超时。下面是 Nginx 的最小配置示例。
```nginx
limit_req_zone $binary_remote_addr zone=api:10m rate=20r/s;
server {
listen 443 ssl;
ssl_certificate /etc/nginx/certs/fullchain.pem;
ssl_certificate_key /etc/n