简介:本文按可复现流程讲解如何在单张高显存加速卡服务器上,用容器部署约270亿参数量化模型服务。内容包括版本核对、容器内加速卡验证、启动参数设置、接口调用、性能与质量测试,以及常见故障排查和回滚方法,读者可据此搭建可验证、可回滚的私有推理环境。
本文适用于个人开发者的远程试验环境、团队私有测试环境、代码辅助工具接入自建服务,以及小规模概念验证。这些场景不涉及高并发生产业务。若要支撑生产流量,还需要评估多卡扩展、批处理、限流和高可用方案。
部署前先估算资源。下表是一份起点参考,实际取值以模型卡和镜像文档为准。
| 资源 | 参考下限 | 说明 |
|---|---|---|
| 加速卡显存 | 按量化格式和上下文长度估算,并预留 10% 以上余量 | 显存不足时服务无法启动或在高负载下崩溃 |
| 系统内存 | 不低于显存容量的 1 倍 | 模型加载和容器运行需要内存 |
| 模型缓存磁盘 | 不少于权重文件大小的 2 倍 | 预留空间给镜像层、日志和临时文件 |
| 服务端口 | 推理端口 8000,仅绑定本机回环地址 | 远程访问通过 SSH 隧道转发 |
版本兼容性需要提前核对。请确认以下四项彼此兼容:
| 组件 | 核对内容 | 记录方式 |
|---|---|---|
| 操作系统 | 长期支持版本 | cat /etc/os-release |
| 加速卡驱动 | 与容器工具包和镜像的 CUDA 版本匹配 | nvidia-smi |
| 容器运行时 | 已安装加速卡容器插件 | docker info |
| 推理镜像 | 版本标签与驱动兼容 | 镜像仓库发布说明 |
模型许可和镜像来源也要先核验。模型需确认下载权限和使用许可。镜像应来自官方仓库或内部可信仓库,并核对镜像摘要(digest),确保拉取的内容与发布内容一致。
以下命令以 NVIDIA 加速卡为例。其他厂商的加速卡,请换成对应厂商的查询工具。
cat /etc/os-releaseuname -rnvidia-smidocker versiondocker info | grep -i runtime
判断标准如下。nvidia-smi 应列出加速卡型号、驱动版本、显存总量和当前占用。若提示命令不存在,说明驱动未安装。若列出了设备但显存占用异常偏高,先检查是否有其他进程占用。docker info 的输出中应包含加速卡运行时相关条目。若缺失,需先安装容器加速卡插件。
请把驱动版本、容器版本和显存总量记录到部署记录中,后续排查兼容性问题时会用到。
docker pull <可信仓库>/<推理镜像>:<版本标签>docker images | grep <推理镜像>docker run --rm --gpus all <可信仓库>/<推理镜像>:<版本标签> nvidia-smi
最后一条命令的输出应与宿主机的 nvidia-smi 一致,包括加速卡型号和显存总量。若宿主机可见而容器内不可见,问题通常出在容器加速卡配置、权限或驱动兼容性上,而不是模型本身。很多“服务启动失败”的根因都在这一步。
sudo mkdir -p /data/model-cache/<模型标识>/<量化版本>sudo chown -R "$(id -u):$(id -g)" /data/model-cachedf -h /data
缓存按模型标识和量化版本分目录存放,避免不同版本的权重文件互相覆盖。权重文件放入目录后,用 ls -lh 检查文件是否齐全,并核对与模型卡上列出的文件清单一致。
以下命令假设镜像提供 OpenAI 兼容的推理接口。<占位符> 需替换为实际值。
read -s LLM_API_KEY && export LLM_API_KEYdocker run -d --name llm-infer \--gpus all \--ipc=host \-p 127.0.0.1:8000:8000 \-v /data/model-cache:/models:ro \<可信仓库>/<推理镜像>:<版本标签> \--model /models/<模型标识>/<量化版本> \--quantization <量化格式> \--served-model-name <模型标识> \--host 0.0.0.0 \--port 8000 \--max-model-len 8192 \--max-num-seqs 4 \--gpu-memory-utilization 0.85 \--api-key "${LLM_API_KEY}"
参数说明如下:
| 参数 | 示例值 | 调整方向 |
|---|---|---|
--max-model-len |
8192 | 首次启动从小值开始,显存充足后再提高 |
--max-num-seqs |
4 | 同时处理的请求数,启动报显存不足时先调低 |
--gpu-memory-utilization |
0.85 | 显存利用比例,与其他进程共用时应调低 |
--quantization |
与模型卡一致 | 填错会导致加载失败或输出质量异常 |
-p 127.0.0.1 |
仅本机回环 | 不要改为 0.0.0.0,避免端口暴露公网 |
API 密钥通过 read -s 输入,不写入脚本或命令历史。
先检查容器状态、日志、监听端口和健康接口:
docker ps --filter name=llm-inferdocker logs --tail 100 llm-inferss -lntp | grep 8000curl -s -m 10 http://127.0.0.1:8000/health
日志中不应出现持续报错、out of memory 或 No such file 等关键字。健康接口应返回 HTTP 200。
健康检查通过后,发送一条测试请求:
curl -s -m 120 http://127.0.0.1:8000/v1/chat/completions \-H "Content-Type: application/json" \-H "Authorization: Bearer ${LLM_API_KEY}" \-d '{"model": "<模型标识>","messages": [{"role": "user", "content": "用 Python 写一个读取 CSV 并计算每列均值的函数。"}],"max_tokens": 512,"temperature": 0.2}'
各字段含义如下。model 必须与 --served-model-name 一致,否则返回模型不存在。max_tokens 限制输出长度。temperature 取较低值,便于比较输出稳定性。-m 120 设置整体超时为 120 秒。
正常响应是一段 JSON,其中 choices[0].message.content 为生成文本,usage 字段给出输入和输出的 token 数。
推理端口只绑定本机回环地址。远程访问通过 SSH 本地端口转发实现:
ssh -N -L 8000:127.0.0.1:8000 <用户名>@<服务器地址>
本机随后访问 http://127.0.0.1:8000 即可。防火墙上不要为 8000 端口添加放行规则。可用 sudo ufw status 或 sudo firewall-cmd --list-all 确认。
安全要求如下:
客户端配置建议如下:
| 配置项 | 开发环境 | 测试环境 |
|---|---|---|
| 接口地址 | http://127.0.0.1:8000/v1(经 SSH 隧道) |
内网网关地址 |
| 模型标识 | 与 --served-model-name 一致 |
同左 |
| 超时时间 | 120 秒 | 60 秒,按实测延迟调整 |
| 密钥 | 本地环境变量 | 密钥管理服务 |
首次接入先用短请求验证连通性,再测试长文本、多轮对话和代码补全场景。开发、测试和生产环境应使用不同密钥。
准备一组固定提示词,每次变更参数或版本后都用同一组测试,结果才有可比性。
| 类别 | 示例任务 | 正确性(0-2) | 指令遵循(0-2) | 可读性(0-2) |
|---|---|---|---|---|
| 代码生成 | 写一个解析日期字符串的函数 | |||
| 长文本理解 | 给出 3000 字材料的五点摘要 | |||
| 指令遵循 | 按指定格式输出 JSON | |||
| 多轮对话 | 三轮追问后修改前文结论 | |||
| 边界输入 | 空输入、超长输入、夹杂乱码 |
每项按 0 至 2 分评分,满分 6 分。评分由人工完成,或使用规则脚本检查格式。
首 token 延迟(TTFT)指从发出请求到收到第一个输出片段的时间。输出速度按以下公式计算:
输出速度(tokens/秒)= 输出 token 数 ÷(整体耗时 − 首 token 延迟)
测量时需使用流式输出("stream": true),记录第一个数据块到达的时间。整体耗时取请求发出到响应结束的时间。
从单请求开始,逐级提高并发数,建议依次为 1、2、4、8。每级连续运行 50 次请求,记录以下指标:
| 并发数 | 中位延迟 p50 | 尾延迟 p95 | 错误率 | 显存占用 | 输出速度 |
|---|---|---|---|---|---|
| 1 | |||||
| 2 | |||||
| 4 | |||||
| 8 |
出现以下任一情况时停止提高并发:错误率超过 1%,p95 延迟超过业务可接受上限,或显存占用持续超过 95%。停止前的并发数即为推荐上限。
每次测试都要记录量化版本、上下文长度、最大并发数、客户端超时和采样参数。缺少这些信息的测试结果不能用于比较或对外引用,也不能直接推广为通用结论。
| 症状 | 可能原因 | 检查命令 | 处理动作 | |
|---|---|---|---|---|
| 容器内看不到加速卡 | 容器加速卡插件未配置 | docker run --rm --gpus all <镜像> nvidia-smi |
检查插件安装和运行时配置,重启容器运行时后重试 | |
| 启动报显存不足 | 上下文或并发设置过大 | `docker logs llm-infer \ | grep -i memory` | 依次降低 --max-model-len、--max-num-seqs,必要时降低 --gpu-memory-utilization |
| 模型加载失败 | 路径错误或权重不完整 | ls -lh /data/model-cache/<模型标识>/<量化版本> |
核对路径和文件清单,重新下载缺失文件 | |
| 量化格式不匹配 | --quantization 与模型不一致 |
`docker logs llm-infer \ | grep -i quant` | 按模型卡修改参数并重启 |
| 端口不可达 | 监听地址或映射配置错误 | `ss -lntp \ | grep 8000与docker port llm-infer` |
确认容器内监听 0.0.0.0,宿主机映射为 127.0.0.1:8000 |
| 客户端超时 | 请求排队或超时设置过短 | 查看日志中的请求耗时 | 提高客户端超时,或降低并发后重新测试 | |
| 模型名不存在 | 请求中的 model 与服务配置不一致 |
对比请求体与 --served-model-name |
统一两边的模型标识 | |
| 输出被截断 | max_tokens 过小或上下文超限 |
查看响应中的 finish_reason |
提高 max_tokens,或缩短输入 |
建议配置以下告警阈值,具体数值需结合基线测试结果调整:
| 指标 | 告警条件 |
|---|---|
| 显存占用 | 连续 5 分钟超过 90% |
| 请求错误率 | 连续 5 分钟超过 1% |
| p95 延迟 | 超过基线值的 50% |
| 服务健康检查 | 连续 3 次失败 |
| 缓存磁盘使用率 | 超过 85% |
部署新版本前,保留上一版镜像标签和启动命令。回滚时执行:
docker stop llm-infer && docker rm llm-inferdocker run -d --name llm-infer ... <上一版镜像标签> ...
回滚后重新执行健康检查和固定测试集,确认