简介:本文面向需要在国产AI加速卡上当天接入开源图像生成模型的工程团队。读完后,你可以按统一清单完成版本冻结、单卡验证、算子排查、图编译、精度验收、压测容量与灰度回滚,并获得可复用的检查表和排障对照表。
模型开源当天,团队最常遇到的问题是模型已经公开,但在自有算力上无法稳定出图。本教程给出一条可执行的路径,让团队在发布当日完成推理适配、基础调优和效果验证,避免出现“模型已开源、算力不可用”的空窗期。
本文以“功能可用、效果可接受、性能可承载、故障可回退”四项作为完成标准。四项同时满足,才算适配完成。只满足功能可用,不能视为完成。
读者包括负责推理落地的算法工程师、维护异构算力集群的运维人员,以及评估国产算力替代方案的技术负责人。阅读前需要具备基本的容器操作经验和 Python 使用经验。
本教程只讨论通用工程方法。文中不涉及任何特定模型、芯片型号、框架或平台的私有接口与参数。涉及云资源时,仅使用对象存储、容器平台、日志服务、监控告警等通用类目。具体型号和版本请以对应组件的官方兼容说明为准。
团队应在开始前填写下面的版本矩阵,并把每一行作为一次适配的记录。
| 字段 | 示例填写要求 | 说明 |
|---|---|---|
| 加速卡型号 | 型号与卡数 | 决定可用精度和显存上限 |
| 驱动与固件版本 | 完整版本号 | 不同版本可能对算子支持不同 |
| 运行时版本 | 完整版本号 | 需与驱动配套 |
| 深度学习框架版本 | 完整版本号 | 不跨大版本混用 |
| 算子库版本 | 完整版本号 | 决定缺失算子能否补齐 |
| 编译工具版本 | 完整版本号 | 影响缓存复用 |
| 容器镜像 digest | sha256 值 | 比标签更可靠 |
| 模型权重校验值 | sha256 值 | 确认权重来源和完整性 |
| 兼容结论 | 通过、有条件通过、不通过 | 附带失败项与原因 |
1. 算力与驱动检查
在节点上确认加速卡在位,并记录驱动版本。检查命令以厂商提供的管理工具为准,例如:
<vendor-smi> --query-device<vendor-smi> --query-driver
确认卡数、显存容量与规划的并发一致。若使用云环境,在控制台确认加速实例规格、镜像和配额。配额不足时,应在发布前申请扩容,不要在发布当天等待。
2. 软件栈检查
拉取镜像时使用 digest 指定版本,避免标签被覆盖:
docker pull <registry>/<image>@sha256:<digest>
进入容器后,记录框架、算子库和编译工具的版本,并与版本矩阵比对。
3. 模型与权重检查
从官方发布渠道下载权重和配置文件,核对校验值:
sha256sum -c model.sha256
校验失败时立即停止,不要尝试手动修改文件。权重应存放在受控的对象存储或内网制品库,访问路径按项目隔离。
4. 测试数据准备
准备不少于 200 条验收提示词,按五类均匀分布:人像、风景、文字渲染、复杂构图、其他。每条提示词配一张参考图或人工评分基线,用于后续精度对比。
5. 权限与流程检查
确认账号具备拉取镜像、读取存储、提交任务和查看日志的权限。生产环境的适配变更必须经过评审,并提前写好回滚方案。
把第二节的版本矩阵填完整,生成基线清单文件,记录模型、框架、算子库、编译工具和镜像的版本信息。
{"model": "<model_name>","weights_sha256": "<sha256>","image_digest": "sha256:<digest>","framework": "<version>","operator_lib": "<version>","compiler": "<version>","driver": "<version>","created_at": "2026-11-18T00:00:00Z"}
同一天内不要同时升级多项底层组件。如果同时升级,出现故障时无法判断原因。
先在单卡上加载模型,执行一次短提示词生成。这一步的目的是暴露三类问题:权重加载失败、算子缺失、显存或内存不足。
python infer_check.py \--weights /data/models/<model_name>/ \--device 0 \--tp-size 1 \--dtype fp16 \--prompt-file prompts/smoke.txt \--height 512 --width 512 \--steps 20 --seed 42 \--out /data/out/smoke
参数说明如下:
--tp-size 为张量并行数,首次验证固定为 1。多卡验证时,必须与可用卡数整除。--dtype 首次使用 fp16 或 bf16。若出现数值异常,再切换到 fp32 对比。--seed 和尺寸、步数保持固定,便于后续复现。运行结束后,日志应输出以下字段:
{"load_time_s": 0,"first_image_time_s": 0,"peak_mem_mb": 0,"missing_ops": [],"warnings": 0,"errors": 0}
如果 missing_ops 不为空,进入步骤3。如果 peak_mem_mb 接近卡的显存上限的 90%,降低分辨率或批大小后重测。
对报错做分类处理。
最小对比脚本的结构如下:
import torchdef compare_op(ref_fn, dev_fn, shape=(1, 64, 32, 32), dtype=torch.float16, seed=0):g = torch.Generator().manual_seed(seed)x = torch.randn(shape, generator=g).to(dtype)ref = ref_fn(x.float()).to(dtype)out = dev_fn(x.to(device="cuda" if False else "<device>")).cpu()diff = (ref.cpu() - out).abs()rel_err = diff.max() / ref.abs().max().clamp_min(1e-6)cos = torch.nn.functional.cosine_similarity(ref.cpu().flatten().float(), out.flatten().float(), dim=0)return {"max_rel_err": float(rel_err), "cosine": float(cos)}
以下阈值可作为起点:fp32 下最大相对误差不超过 1e-3;fp16 或 bf16 下不超过 1e-2;余弦相似度不低于 0.999。阈值需要根据具体算子和业务调整,并记录调整原因。
不要为赶进度关闭数值检查,也不要随意屏蔽告警。关闭检查会让输出失真的问题延后暴露,排查成本更高。
完成算子兼容后,切换到编译路径。保留两个开关:动态图模式用于调试定位,编译模式用于性能测试。两种模式的输出差异需要记录在验收报告中。
编译缓存的键值应包含以下信息:镜像 digest、权重校验值、编译工具版本和编译配置的哈希。缓存键变化时,必须重新编译。这样可以避免旧缓存污染新结果。
首次编译耗时较长。正式压测前,先用 20 条预热提示词跑完编译,再开始计时。
使用固定随机种子、固定尺寸和固定步数,对比基线设备或参考实现的输出。对生成任务,不应只追求像素级一致。建议按下表给各项打分,每项 0 至 5 分,再按权重加总。
| 验收维度 | 权重 | 评分要点 |
|---|---|---|
| 结构一致性 | 25% | 主体位置、构图比例是否与基线一致 |
| 语义保留 | 20% | 提示词中的关键对象是否都出现 |
| 文字渲染 | 15% | 文字是否可读、有无错字和断笔 |
| 人脸与手部异常率 | 20% | 异常样本占比,与基线对比 |
| 边缘细节 | 10% | 发丝、纹理边缘是否清晰 |
| 色彩漂移 | 10% | 与基线的色彩直方图差异 |
阈值由产品和算法共同确认。作为起点,可以设定:总分不低于基线的 98%;人脸与手部异常率不高于基线加 1 个百分点;文字渲染得分不低于 3 分。
压测口径需要写清楚,否则结果无法比较。
需要记录的指标包括:首图延迟、整图生成时延、吞吐、显存占用、排队时间。依据稳态吞吐计算单卡可承载并发,并预留 20% 至 30% 的安全水位。
在线低延迟场景和离线批量场景应使用不同的资源池,两者不要混用。
将通过验收的版本封装为推理服务,接入负载均衡、日志服务和监控告警。核心指标如下:
所有指标和告警都要带上实例 ID、镜像 digest 和模型版本标签。出现异常时,可以直接定位到具体版本。
发布前,逐项确认下表。全部通过后,才能进入灰度发布。
| 检查项 | 通过标准 |
|---|---|
| 验收提示词复现 | 200 条提示词,同一种子两次输出结构一致 |
| 稳定性压测 | 连续运行 2 小时,无非预期进程退出 |
| 延迟阈值 | 稳态 P95 延迟不超过业务约定值 |
| 兼容告警 | 日志中兼容类告警连续 10 分钟为 0 |
| 效果验收 | 按步骤5的评分表,总分不低于基线的 98% |
| 回滚演练 | 从新版本回退到基线版本,耗时不超过 15 分钟 |
回滚演练的步骤如下:
多数情况由权重格式、精度类型或内存映射不兼容引起。先执行权重校验,再核对版本矩阵。如果校验通过,把 --dtype 切换到 fp32 重测,确认是否为精度类型问题。
这通常是编译和缓存预热不足。冷启动和稳态指标要分开统计。缓存目录应挂载到持久化存储,服务重启后可以直接复用。
多为算子语义偏差。用步骤3的最小张量脚本逐个对比关键算子,找到偏差最大的那一个,再决定替换实现还是提交给维护方。
按顺序检查三项:显存是否发生交换,请求队列是否阻塞,单实例是否过载。若单实例过载,按容量规划增加实例数,不要单纯提高并发上限。
逐一固定随机种子、采样参数和调度策略。若关闭非确定性选项后结果稳定,说明问题来自调度或并行计算的顺序差异。
性能优化:优先做编译优化、批量合并和显存复用,最后再考虑量化。量化后必须做效果回归。在同一套 200 条验收提示词上对比量化前后的结果,总分下降不超过 2%,人脸与手部异常率不得上升。
灰度发布:按 5%、20%、50