简介:面向开发者和运维人员,按选型标准、显存估算、服务启动、接口联调、压测监控到回滚演练的顺序,给出可执行的命令、参数示例和上线检查清单。读者可据此完成端侧或服务端部署,并在版本异常时快速切回旧版本,降低上线风险。
本文说明如何把一款参数量为0.8B的视觉语言模型部署为可调用的推理服务。模型可接收纯文本、图像和视频输入。发布页提供的模型标识记为 <model-id>,下文出现的版本号和路径都是占位示例,执行前请替换为发布页给出的真实值。
原始资料披露的关键参数如下,部署前请逐项核对:
部署完成后,应达到四个结果。第一,服务进程稳定运行,模型加载成功,没有内存溢出。第二,HTTP接口可以完成文本和图像推理,并返回结构化结果。第三,日志、监控和告警覆盖关键指标。第四,旧版本保留,可以快速回滚,升级不影响已有调用方。
本文适合三类读者。开发者负责把模型接入业务代码。运维人员负责资源、网络和上线。技术负责人需要评估部署方案的成本与风险。
同一个模型可以落在三种主要形态上。选择时先回答两个问题:图像和文本能否离开内网,负载是否需要多副本伸缩。
| 场景 | 适用条件 | 不适用条件 | 资源重点 |
|---|---|---|---|
| 端侧设备 | 需要离线运行,单次请求量小 | 需要高并发或长上下文 | 内存、功耗、发热、模型包更新 |
| 私有服务器 | 数据不能出域,并发量稳定 | 没有可用的加速卡或内网机房 | 显存、并发数、访问控制 |
| 云上容器 | 负载波动大,需要多副本 | 数据不允许进入公有云 | 镜像版本、健康检查、扩缩容 |
资源门槛需要先算清楚。权重体积是硬下限。按0.8B乘以每参数字节数推算,BF16约需1.6 GB,INT8约需0.8 GB,INT4约需0.4 GB。这些数字不含运行时开销,实际占用需要以实测为准。
选择建议如下。
不推荐在没有加速卡的服务器上套用本文的服务端命令。那种环境需要换用支持CPU推理的运行时,并重新测算性能。
建议锁定以下版本,并记录在部署文档中。
| 组件 | 要求 | 说明 |
|---|---|---|
| 操作系统 | 64位Linux | 示例使用Ubuntu 22.04 |
| Python | 3.10及以上 | 使用独立虚拟环境 |
| GPU驱动与CUDA | 与推理框架的要求一致 | 以框架发布说明为准 |
| 推理框架 | 固定到具体版本号 | 本文示例使用vLLM,版本写为 <锁定版本> |
创建目录和虚拟环境:
sudo mkdir -p /opt/vlm /models/releases /etc/vlmsudo useradd --system --no-create-home vlmpython3 -m venv /opt/vlm/venvsource /opt/vlm/venv/bin/activatepip install "vllm==<锁定版本>"
下载权重。建议指定commit或tag,避免下载到未经确认的版本:
pip install -U huggingface_hubhuggingface-cli download <model-id> --revision <commit或tag> \--local-dir /models/releases/<版本号>
校验文件完整性。如果发布方提供SHA256SUMS,直接校验:
cd /models/releases/<版本号>sha256sum -c SHA256SUMS
如果没有提供,就自行生成并保存,供以后比对:
sha256sum *.safetensors *.json > SHA256SUMS
校验通过后,将版本目录改为只读,并指向当前版本:
sudo chmod -R a-w /models/releases/<版本号>sudo ln -sfn /models/releases/<版本号> /models/current
服务端显存占用可以拆成三部分,公式如下:
总占用约等于 M_w 加 M_kv 加 M_runtime。
L、H_kv、d都可以在config.json中查到,字段名因模型架构而异。
下面用一组假设值演示计算。假设L=24、H_kv=4、d=128、T=8192、B=4、s=2。这组数值只用于演算,并非该模型的真实结构。
KV缓存占用为 2 × 24 × 4 × 128 × 8192 × 4 × 2 字节,约等于1.61 GB。加上BF16权重约1.6 GB和2 GB运行时预留,合计约5.2 GB。
这个结果说明两件事。第一,并发数和单序列长度会同时放大KV缓存。第二,如果不设上限,框架可能按262,144 token预留缓存,直接耗尽显存。因此启动时要用 --max-model-len 限制单序列长度。
端侧设备的内存通常比服务器紧张。规划时需要分别测量以下四项。
如果任一项超出设备能力,应换用更低精度的量化版本,或降低输入图像的分辨率。量化格式和推理引擎需要与设备的硬件支持相匹配,本文不指定具体设备上的数值。
先写入环境变量文件。密钥只放在这里,不写进代码、脚本或日志。
sudo tee /etc/vlm/service.env > /dev/null <<'EOF'VLLM_API_KEY=<随机生成的长字符串>EOFsudo chown root:vlm /etc/vlm/service.envsudo chmod 640 /etc/vlm/service.env
生成随机密钥可以使用 openssl rand -hex 32。
创建systemd服务文件 /etc/systemd/system/vlm-infer.service:
[Unit]Description=VLM inference serviceAfter=network-online.targetWants=network-online.target[Service]User=vlmGroup=vlmEnvironmentFile=/etc/vlm/service.envExecStart=/opt/vlm/venv/bin/vllm serve /models/current \--served-model-name vlm-0.8b \--host 127.0.0.1 \--port 8000 \--dtype bfloat16 \--max-model-len 16384 \--gpu-memory-utilization 0.80 \--max-num-seqs 8 \--limit-mm-per-prompt '{"image": 1, "video": 0}'Restart=on-failureRestartSec=5ReadOnlyPaths=/modelsNoNewPrivileges=true[Install]WantedBy=multi-user.target
启动服务并查看状态:
sudo systemctl daemon-reloadsudo systemctl enable --now vlm-infersudo systemctl status vlm-infer --no-pagerjournalctl -u vlm-infer -n 100 --no-pager
模型加载耗时取决于磁盘和显卡性能。请等待日志中出现服务启动完成的记录后,再进行联调。
启动参数的含义如下。
| 参数 | 作用 | 调整方向 |
|---|---|---|
--served-model-name |
接口中使用的模型名 | 与业务代码保持一致 |
--host 127.0.0.1 |
只监听本机 | 外部访问经网关转发 |
--dtype bfloat16 |
计算精度 | 与量化版本和硬件支持对应 |
--max-model-len |
单序列最大长度,控制KV缓存 | 显存不足时调小 |
--gpu-memory-utilization |
框架可使用的显存比例 | 为系统和其他进程留出余量 |
--max-num-seqs |
最大并发序列数 | 从小值开始,按压测结果上调 |
--limit-mm-per-prompt |
单次请求允许的图像和视频数量 | 按业务需要设置,视频通常设为0 |
第一步,检查健康状态。返回HTTP 200即表示服务已就绪:
curl -i http://127.0.0.1:8000/health
第二步,确认模型名称已注册:
curl -fsS http://127.0.0.1:8000/v1/models \-H "Authorization: Bearer $VLLM_API_KEY"
第三步,发送文本请求:
curl -fsS http://127.0.0.1:8000/v1/chat/completions \-H "Content-Type: application/json" \-H "Authorization: Bearer $VLLM_API_KEY" \-d '{"model": "vlm-0.8b","messages": [{"role": "user", "content": "用一句话介绍你自己。"}],"max_tokens": 128,"temperature": 0.2}'
第四步,发送图像请求。图像以base64数据URI的形式放入消息内容。下面的占位符需替换为真实的编码内容:
curl -fsS http://127.0.0.1:8000/v1/chat/completions \-H "Content-Type: application/json" \-H "Authorization: Bearer $VLLM_API_KEY" \-d '{"model": "vlm-0.8b","messages": [{"role": "user","content": [{"type": "text", "text": "描述图中的主要内容,不超过50字。"},{"type": "image_url","image_url": {"url": "data:image/jpeg;base64,<BASE64内容>"}}]}],"max_tokens": 128,"temperature": 0.2}'
图像应先压缩到业务可接受的尺寸,再进行base64编码。编码后体积会增加约三分之一,网关的请求体大小限制需要相应放宽。
调用方的Python示例如下。连接超时设为3秒,读取超时设为60秒,超时时间应按业务的响应要求调整:
import osimport requestsurl = "http://127.0.0.1:8000/v1/chat/completions"headers = {"Authorization": f"Bearer {os.environ['VLLM_API_KEY']}"}payload = {"model": "vlm-0.8b","messages": [{"role": "user", "content": "用一句话介绍你自己。"}],"max_tokens": 128,"temperature": 0.2,}resp = requests.post(url, json=payload, headers=headers, timeout=(3, 60))resp.raise_for_status()data = resp.json()print(data["choices"][0]["message"]["content"])print(data["usage"])
错误处理建议按下表对应排查。具体返回以服务实际输出为准。
| 状态码 | 常见原因 | 处理方式 |
|---|---|---|
| 400 | 请求格式错误,图像格式或尺寸不被支持 | 校验请求体和图像格式 |
| 401 | 密钥缺失或错误 | 检查Authorization头和环境变量文件 |
| 413 | 请求体超过网关限制 | 压缩图像,或按需调整网关限制 |
| 429 | 网关限流 | 客户端退避重试 |
| 503 | 模型未就绪或并发饱和 | 查看服务状态,降低调用频率 |
| 500 | 服务内部异常 | 根据request_id查看服务日志 |
推理服务不应直接暴露在公网上。网关统一负责TLS终止、鉴权、限流和请求体大小限制。以下是一段Nginx配置示例:
location /v1/ {client_max_body_size 10m;proxy_read_timeout 60s;proxy_pass http://127.0.0.1:8000;}
网络层面,只开放网关端口,并限定来源网段。例如使用ufw时,可以只允许内网段访问443端口:
sudo ufw allow from 10.0.0.0/8 to any port 443 proto tcpsudo ufw deny 8000/tcp
模型目录通过 ReadOnlyPaths 只读挂载,服务进程无法修改权重文件。服务进程以独立的 vlm 用户运行,不使用root权限。
端侧设备通常不运行上文的vLLM命令,而是使用设备支持的量化格式和推理引擎。部署时按以