简介:本文面向开发者与运维人员,给出统一自回归图像模型从资源规划、环境安装、服务启动、上线验证到故障排查与回滚的操作步骤,包含版本基线、关键参数、健康检查路径和告警阈值。读者按步骤执行即可搭建可监控、可回滚的图像生成服务。
本文的部署对象是一类开源统一自回归图像模型,它在同一个 Transformer 中完成图像理解、推理与生成。权重格式、推理入口和参数名称以该模型官方仓库的说明为准。文中用 <占位符> 标注需要替换的内容,执行前逐一替换。
| 组件 | 推荐版本 | 说明 |
|---|---|---|
| 操作系统 | Ubuntu 22.04 LTS | 其他发行版需自行验证驱动和库的兼容性 |
| NVIDIA 驱动 | 535 及以上 | 需支持所选的 CUDA 版本 |
| CUDA 运行时 | 12.1 | 与 PyTorch 官方 cu121 wheel 对应 |
| Python | 3.10 或 3.11 | 以模型依赖声明的支持范围为准 |
| PyTorch | 与 CUDA 匹配的 2.x 版本 | 模型要求的最低版本优先 |
| 模型权重 | 固定版本号,例如 v1.0.0 | 必须配套发布方提供的 sha256 校验值 |
nvidia-sminvidia-smi --query-gpu=name,memory.total,driver_version --format=csvdf -h /datafree -g
确认显卡型号、显存总量和驱动版本与基线一致。若 nvidia-smi 报错或无输出,先解决驱动问题,再安装模型依赖。
sudo useradd -r -m -s /usr/sbin/nologin imggensudo mkdir -p /opt/imggen/releases /data/models /data/outputs /etc/imggensudo chown -R imggen:imggen /opt/imggen /data/models /data/outputssudo chmod 750 /etc/imggen
服务以非 root 用户运行。权重目录只需要服务用户的读权限,输出目录需要写权限。配置目录仅允许 root 和服务用户访问。
sudo -u imggen python3.11 -m venv /opt/imggen/venvsudo -u imggen /opt/imggen/venv/bin/pip install --upgrade pipsudo -u imggen /opt/imggen/venv/bin/pip install torch==<版本号> --index-url https://download.pytorch.org/whl/cu121sudo -u imggen /opt/imggen/venv/bin/pip install -r /opt/imggen/releases/v1.0.0/requirements.txt
requirements.txt 中每个依赖都应写明精确版本,防止不同机器之间出现版本漂移。安装完成后执行下面的命令:
sudo -u imggen /opt/imggen/venv/bin/python -c "import torch; print(torch.__version__, torch.cuda.is_available())"
输出末尾必须是 True。若为 False,说明 PyTorch 与驱动或 CUDA 版本不匹配,需要重新安装对应的 wheel。
cd /data/modelssudo -u imggen mkdir -p unified-ar-image/v1.0.0cd unified-ar-image/v1.0.0sudo -u imggen curl -fL -o model.safetensors "<权重下载地址>"echo "<官方公布的sha256值> model.safetensors" | sha256sum -c -
校验输出必须是 model.safetensors: OK。校验失败时删除文件并重新下载,不要跳过校验直接启动服务。下载地址、访问令牌等敏感信息不要写入脚本或 shell 历史。需要令牌时,从密钥管理服务取出后通过临时环境变量传入,使用完毕后执行 unset。
显存占用大致由三部分构成:权重、KV 缓存和激活与框架开销。
该公式假设模型未使用分组查询注意力等压缩结构。实际取值以模型配置文件为准。框架开销和显存碎片无法从公式中得出,必须通过压测确认。估算结果只作为起点,最终规格以压测为准。
磁盘规划按以下方式估算:权重与依赖空间加上输出目录的日均产量乘以保留天数,再预留 50% 的余量。
网络方面,推理服务只监听本机回环地址 127.0.0.1:8000,对外只开放 443 端口。防火墙配置如下,执行前先确认 SSH 端口,避免把自己锁在外面:
sudo ufw allow 22/tcpsudo ufw allow 443/tcpsudo ufw default deny incomingsudo ufw enable
创建 /etc/imggen/imggen.env。下列参数名为示例,需与服务代码中的实际参数对齐:
MODEL_PATH=/data/models/unified-ar-image/v1.0.0/model.safetensorsOUTPUT_DIR=/data/outputsLISTEN_HOST=127.0.0.1LISTEN_PORT=8000MAX_BATCH_SIZE=1MAX_CONCURRENCY=2MAX_RESOLUTION=1024MAX_NEW_TOKENS=<按模型上限设置>REQUEST_TIMEOUT_S=300AUTH_ENABLED=trueAPI_KEY_FILE=/etc/imggen/api_keyLOG_LEVEL=INFO
配置文件和密钥文件的权限都应设为 600:
sudo chmod 600 /etc/imggen/imggen.envsudo install -m 600 -o imggen -g imggen /dev/null /etc/imggen/api_key
API 密钥从密钥管理服务获取后写入 /etc/imggen/api_key,不要写在配置文件或代码里。
创建 /etc/systemd/system/imggen.service:
[Unit]Description=Unified AR image inference serviceAfter=network-online.targetWants=network-online.target[Service]Type=simpleUser=imggenGroup=imggenWorkingDirectory=/opt/imggen/currentEnvironmentFile=/etc/imggen/imggen.envExecStart=/opt/imggen/venv/bin/python -m <服务入口模块> --host ${LISTEN_HOST} --port ${LISTEN_PORT}Restart=on-failureRestartSec=5TimeoutStartSec=600TimeoutStopSec=60NoNewPrivileges=trueProtectSystem=strictReadWritePaths=/data/outputs[Install]WantedBy=multi-user.target
TimeoutStartSec 设为 600 秒,是为了给大权重文件留出加载时间。启动并检查状态:
sudo systemctl daemon-reloadsudo systemctl enable --now imggensudo systemctl status imggen --no-pagerss -lntp | grep 8000
日志统一由 journald 收集,查看方式为 journalctl -u imggen -n 200 --no-pager。
使用 nginx 做 TLS 终止和来源限制。示例配置写入 /etc/nginx/sites-available/imggen,server_name 与证书路径替换为实际值:
server {listen 443 ssl http2;server_name img-api.example.internal;ssl_certificate /etc/nginx/certs/img-api.crt;ssl_certificate_key /etc/nginx/certs/img-api.key;client_max_body_size 2m;location /v1/ {allow 10.0.0.0/8;deny all;proxy_pass http://127.0.0.1:8000;proxy_http_version 1.1;proxy_set_header Host $host;proxy_set_header X-Request-ID $request_id;proxy_read_timeout 300s;proxy_send_timeout 300s;}}
proxy_read_timeout 必须大于应用中的 REQUEST_TIMEOUT_S,否则 nginx 会先于应用断开连接,返回 504。应用的健康检查路径不需要对外开放,只在本机探测。
生效前检查语法:
sudo nginx -t && sudo systemctl reload nginx
最小可用拓扑的数据流如下:
请求入口(nginx)→ 鉴权与限流 → 同步推理服务,或写入任务队列 → 推理 worker → 输出目录或对象存储 → 监控与日志。
选择条件如下:
REQUEST_TIMEOUT_S 之内、并发数可控时,使用同步接口。同步接口的并发上限由 MAX_CONCURRENCY 决定。超过该值的请求应返回 429,不要无限排队占用连接。
服务应提供两个接口:
/healthz:进程存活即返回 200。/readyz:模型已加载且 GPU 可用时返回 200,否则返回 503。
curl -sS -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8000/healthzcurl -sS -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8000/readyz
若服务代码没有这两个接口,上线前必须补上。否则无法区分“进程在运行”与“模型已可用”两种状态,负载均衡会把流量导入尚未加载完成的实例。
冒烟测试使用一条固定、无敏感内容的提示词:
curl -sS -X POST https://img-api.example.internal/v1/generate \-H "Authorization: Bearer $(cat /etc/imggen/api_key)" \-H "Content-Type: application/json" \-d '{"prompt":"一只坐在窗台上的橘猫","width":512,"height":512,"seed":42}' \-o /tmp/smoke.json -w "%{http_code} %{time_total}\n"
请求字段名以接口文档为准。验收标准是返回 200,响应中包含模型版本号和耗时,输出文件可以正常打开。
此外,准备 10 组固定的提示词和随机种子作为黄金样本。首次上线时保存输出图像及其 sha256 值作为基线。之后每次发布或升级依赖,都用同一批样本重新生成,并对比哈希与人工抽检结果。哈希不一致不代表质量下降,但需要确认差异来源。
压测用于确定 MAX_RESOLUTION、MAX_BATCH_SIZE 和 MAX_CONCURRENCY 的取值。建议至少覆盖以下组合:
| 序号 | 并发 | 分辨率 | 输出长度 | 批大小 | 记录项 |
|---|---|---|---|---|---|
| 1 | 1 | 512 | 中等 | 1 | 单次耗时、显存峰值 |
| 2 | 2 | 最大 | 最大 | 1 | 显存峰值、是否出现 OOM |
| 3 | 4 | 中等 | 最大 | 2 | p95 延迟、错误率 |
| 4 | 最大并发 | 最大 | 最大 | 最大 | 排队长度、超时比例 |
出现 OOM、5xx 错误率超过 1%、或 p95 延迟超过业务目标时,停止加压,把该组合前一档的参数记为上限。压测结果是本环境的实测数据,不要把它当作对外的性能承诺。
每条请求日志至少包含以下字段:request_id、model_version、请求路径、状态码、总耗时、排队耗时、用户标识的哈希值、提示词长度。
提示词原文不写入日志。写入任何日志之前,先对手机号、邮箱和证件号码等信息替换为 [REDACTED]。排查问题时,用 request_id 关联 nginx 日志与应用日志即可。
日志保留 30 天。在 /etc/systemd/journald.conf 中设置:
[Journal]SystemMaxUse=2GMaxRetentionSec=30day
修改后执行 sudo systemctl restart systemd-journald 生效。
下表阈值是起始值,应在压测基线建立后调整。
| 指标 | 采集方式 | 警告 | 严重 |
|---|---|---|---|
| GPU 利用率 | nvidia-smi 或 DCGM exporter | 持续 15 分钟高于 90%,且排队持续增长 | 排队超时比例高于 5% |
| 显存占用 | 同上 | 高于 92% | 高于 97%,或出现 OOM 日志 |
| 排队长度 | 应用指标 | 超过 MAX_CONCURRENCY 的 3 倍 | 超过 10 倍,或 5 分钟内持续增长 |
| 5xx 错误率 | nginx 日志 | 5 分钟内高于 1% | 5 分钟内高于 5% |
| p95 延迟 | 应用指标 | 高于上线基线的 1.5 倍 | 高于上线基线的 2 倍 |
| 磁盘使用率 | df | /data 高于 80% | /data 高于 90% |
| 健康检查 | 外部探测 | 连续 2 次失败 | 连续 3 次失败 |
| 现象 | 可能原因 | 排查方法 |
|---|---|---|
| 启动失败,日志提示 CUDA 不可用 | 驱动与 PyTorch 的 CUDA 版本不匹配 | 执行 1.4 节的 Python 检查命令,并核对 nvidia-smi 输出 |
| 加载权重时 OOM | 显存不足 | 降低 MAX_RESOLUTION 或 MAX_BATCH_SIZE 后重启,并用 nvidia-smi 确认无残留进程 |
| /readyz 长时间返回 503 | 权重路径错误、文件权限不足或仍在加载 | 查看 journalctl 日志,核对 MODEL_PATH 与文件属主 |
| 启动报端口占用 | 旧进程未退出 | 用 ss -lntp 找到占用 8000 端口的 PID,确认后再处理 |
| 返回 401 | API 密钥错误或文件权限异常 | 检查 /etc/imggen/api_key 的内容与属主,不要在日志中打印密钥 |
| 返回 504 | 生成耗时超过代理超时 | 确认 proxy_read_timeout 大于 REQUEST_TIMEOUT_S,并检查排队长度 |
| 磁盘写满 | 输出文件未清理 | 用 du 统计 /data/outputs,按保留策略清理过期文件 |
| 输出与黄金样本哈希不一致 | 权重或依赖版本漂移 | 核对 sha256 值与 requirements.txt 的版本,再对比样本 |
输出清理可以用定时器完成,只删除超过保留天数的文件,例如保留 7 天:
sudo -u imggen find /data/outputs -type f -mtime +7 -print
先执行不带删除动作的版本确认范围,再加上 -delete 参数执行。
每次发布都放在独立目录中,例如 /opt/imggen/releases/v1.0.0。/opt/imggen/current 是指向当前版本的符号链接。回滚时只切换链接,不覆盖旧版本文件:
sudo ln -sfn /opt/imggen/releases/v0.9.0 /opt/imggen/currentsudo systemctl restart imggencurl -sS -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8000/readyz
以下情况应立即回滚:
回滚后保留故障版本的日志和配置,用于事后分析。权重文件保留在 /data/models 中,不随回滚删除。
| 周期 | 检查项 | 通过标准 |
|---|---|---|
| 每日 | 服务状态与 /readyz | 返回 200,无连续失败 |
| 每日 | 5xx 错误率与 p95 延迟 | 均在警告阈值以下 |
| 每日 | /data 磁盘使用率 | 低于 80% |
| 每周 | 输出清理任务执行结果 | 过期文件已删除,任务无报错 |
| 每周 | 日志与监控告警记录 | 告警均有处理记录 |
| 每次发布前 | 权重 sha256 与依赖版本 | 与发布说明一致 |
| 每次发布后 | 冒烟测试与黄金样本对比 | 功能正常,哈希差异已确认来源 |
| 每月 | 密钥轮换 | API 密钥已更新,旧密钥已失效 |
| 每季度 | 压测基线复核 | 参数上限与告警阈值已按最新数据调整 |