开源多模态大模型上线部署与运维实操指南

作者:很酷cat2026.11.18 11:47浏览量:0

简介:本文按资源规划、启动配置、健康检查、网关接入、压测记录、回滚和故障排查的顺序,给出可替换参数的启动脚本、systemd 配置、检查脚本和上线检查表。团队照着做,能减少上线后的反复调试,出现问题时也能快速定位并安全回退。

一、适用范围

本文以 vLLM 提供的 OpenAI 兼容接口为例。其他推理框架的思路相同,只需把参数名替换成对应框架文档中的写法。模型能力、许可证和适用范围不在本文讨论范围内,这些内容以模型卡、许可证和团队自己的评测结果为准。

命令中的版本号、路径和域名都是占位内容,执行前需要替换成团队的实际值。

二、上线检查表

上线前逐项确认以下内容,全部打勾后再切换流量。

  • 模型权重文件的 SHA256 与版本记录一致。
  • vLLM、CUDA 驱动和 Python 依赖已固定版本号。
  • API Key 通过环境变量注入,没有写入代码、镜像或日志。
  • 健康检查脚本返回成功,/v1/models 能列出目标模型。
  • 一条纯文本请求和一条图文请求都返回结构正确的结果。
  • 网关已启用 TLS、认证、限流和超时控制。
  • systemd 已配置自动重启,监控告警已接入。
  • 上一版本的模型和配置已保留,回滚步骤至少演练过一次。

三、部署架构

推理进程只监听 127.0.0.1:8000,外部流量只能经过网关访问。网关监听 443 端口,负责证书、认证、限流和超时。

测试环境可以只部署一个副本。生产环境至少部署两个副本,放在不同机器上,前面接负载均衡。

模型权重按版本存放,例如 /data/models/your-model/v1。权重目录设为只读,升级时新建目录,不覆盖旧版本。

四、启动配置

把参数和密钥放进环境文件,权限设为 600,只允许服务账号读取。

  1. # /etc/vllm/vllm.env
  2. VLLM_API_KEY=替换为从密钥管理系统注入的值
  3. MODEL_PATH=/data/models/your-model/v1
  4. SERVED_NAME=mm-model
  5. HOST=127.0.0.1
  6. PORT=8000
  7. MAX_MODEL_LEN=8192
  8. GPU_MEM_UTIL=0.90
  9. MAX_NUM_SEQS=8
  10. TP_SIZE=1
  11. MM_LIMIT={"image": 2}

API Key 通过 VLLM_API_KEY 环境变量读取,不放在命令行参数里。命令行参数会被 ps 等工具看到,存在泄露风险。

启动脚本 /opt/vllm/start.sh 如下。

  1. #!/usr/bin/env bash
  2. set -euo pipefail
  3. : "${MODEL_PATH:?MODEL_PATH 未设置}"
  4. : "${SERVED_NAME:?SERVED_NAME 未设置}"
  5. exec vllm serve "$MODEL_PATH" \
  6. --served-model-name "$SERVED_NAME" \
  7. --host "$HOST" --port "$PORT" \
  8. --max-model-len "$MAX_MODEL_LEN" \
  9. --gpu-memory-utilization "$GPU_MEM_UTIL" \
  10. --max-num-seqs "$MAX_NUM_SEQS" \
  11. --tensor-parallel-size "$TP_SIZE" \
  12. --limit-mm-per-prompt "$MM_LIMIT"

exec 让 vLLM 替换启动脚本的进程,systemd 才能直接管理它。--limit-mm-per-prompt 的写法随 vLLM 版本变化,以所用版本的文档为准。模型要求 --trust-remote-code 时才加这个参数,并先确认代码来源可信。

systemd 配置 /etc/systemd/system/vllm.service 如下。

  1. [Unit]
  2. Description=vLLM multimodal inference
  3. After=network-online.target
  4. Wants=network-online.target
  5. StartLimitIntervalSec=600
  6. StartLimitBurst=5
  7. [Service]
  8. User=vllm
  9. Group=vllm
  10. EnvironmentFile=/etc/vllm/vllm.env
  11. ExecStart=/opt/vllm/start.sh
  12. Restart=on-failure
  13. RestartSec=10
  14. TimeoutStartSec=900
  15. LimitNOFILE=65535
  16. [Install]
  17. WantedBy=multi-user.target

TimeoutStartSec 设为 900 秒,给大模型加载留出时间。StartLimitBurst 限制短时间内的重启次数,避免配置错误时无限重启。

启动和查看日志的命令如下。

  1. sudo systemctl daemon-reload
  2. sudo systemctl enable --now vllm
  3. sudo systemctl status vllm
  4. journalctl -u vllm -f

五、健康检查

进程启动成功不等于服务可用。模型加载需要时间,加载期间接口可能无法返回结果。

检查分三层。第一层确认 HTTP 服务存活,第二层确认模型已注册可用,第三层确认图文请求能返回结果。

  1. #!/usr/bin/env bash
  2. set -euo pipefail
  3. source /etc/vllm/vllm.env
  4. # 存活检查:HTTP 服务是否响应
  5. curl -fsS -m 5 http://127.0.0.1:8000/health >/dev/null
  6. # 就绪检查:模型是否已注册
  7. curl -fsS -m 5 -H "Authorization: Bearer ${VLLM_API_KEY}" \
  8. http://127.0.0.1:8000/v1/models | grep -q "${SERVED_NAME}"
  9. echo "health check passed"

图文请求用于验证完整链路。图片地址需要能被推理机访问。

  1. curl -fsS http://127.0.0.1:8000/v1/chat/completions \
  2. -H "Authorization: Bearer ${VLLM_API_KEY}" \
  3. -H "Content-Type: application/json" \
  4. -d '{
  5. "model": "mm-model",
  6. "messages": [{"role": "user", "content": [
  7. {"type": "text", "text": "用一句话描述这张图"},
  8. {"type": "image_url", "image_url": {"url": "https://example.com/test.jpg"}}
  9. ]}],
  10. "max_tokens": 64
  11. }'

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