CUDA 兼容性怎么查？驱动、Toolkit、PyTorch 与容器诊断指南

直接答案：CUDA 兼容性不能用一个“CUDA 版本”判断。必须同时确认 GPU 架构、宿主驱动、应用实际加载的用户态库、框架二进制的构建标签、容器映射、自定义扩展和真实工作负载。最可靠的顺序是先识别任务，再采集分层证据，运行最小框架与编译探针，最后用代表性算子和回滚演练放行。

本文于 2026-09-27 复核 NVIDIA CUDA Compatibility、CUDA 13.4 Release Notes、Linux Installation Guide、Container Toolkit 与 PyTorch 官方安装入口。文中的命令是证据采集示例，不会替你修改驱动；任何版本表都应在实施当天回到官方页面复核。

先纠正最常见误区：nvidia-smi 不是 Toolkit 版本

nvidia-smi 顶部显示的 CUDA Version 表示当前驱动可支持的 CUDA 驱动 API 上限；nvcc --version 显示当前 PATH 找到的 Toolkit 编译器；torch.version.cuda 表示 PyTorch 二进制构建时绑定的 CUDA 运行时家族。三个值可以不同，差异本身不等于故障。

NVIDIA 官方兼容文档区分向后兼容、小版本兼容和 forward compatibility。CUDA 11 之后，同一大版本族可在满足最低驱动的前提下使用小版本兼容，但新功能、PTX 与目标架构仍有限制。CUDA 13.4 的 Linux 安装文档还明确将 Toolkit 与驱动独立安装和版本化。因此，先问“应用实际用了哪一层”，再判断需要升级什么。

对应的一手入口是 CUDA Compatibility、Minor Version Compatibility、CUDA Toolkit Release Notes、Linux Installation Guide、NVIDIA Container Toolkit与 PyTorch Start Locally。它们分别提供厂商支持范围，但不替目标主机完成安装和业务验收。

一分钟采集：先生成事实，不要先重装

nvidia-smi
which nvcc || where nvcc
nvcc --version
python -c "import json, torch; print(json.dumps({'torch':torch.__version__,'built_cuda':torch.version.cuda,'available':torch.cuda.is_available(),'devices':torch.cuda.device_count()}, ensure_ascii=False))"
python -m pip freeze

容器环境还要保存镜像摘要、宿主驱动和容器内动态库路径。采集结果只用于定位；只有目标算子、模型和负载在正确性、性能与恢复门槛上通过，才构成上线证据。

四十项兼容性与迁移检查

下面每一项都对应独立故障面。执行时填写证据位置、负责人、结论和复查日期；不能用另一项通过替代。

二十个常见现场症状怎么分层处理

以下不是“复制即修复”的命令清单，而是从症状回到证据层的排查顺序。每个结论都要在目标环境复现。

按部署形态执行：从开发机到集群的运维剧本

个人开发机的最小方案

个人开发机也要避免把所有层混在全局环境。先用官方框架安装选择器创建独立虚拟环境，确认预编译包能完成目标任务；只有编译自定义扩展时才增加 Toolkit。把项目依赖锁文件、安装命令和最小探针放进项目，但不提交机器凭据或巨大二进制。显卡驱动通过操作系统支持的方式维护，更新前保留当前驱动、框架和探针结果。若多个项目需要不同 CUDA 运行库，优先用各自环境或容器隔离，不要持续改系统级符号链接。

团队共享工作站的最小方案

共享工作站需要把宿主驱动视为公共基础设施，由明确负责人维护；项目各自使用容器或隔离环境管理框架与用户态依赖。设备分配使用调度或明确的 CUDA_VISIBLE_DEVICES，而不是口头约定。每次驱动维护前列出受影响项目与最低要求，在一台或一个时段完成 canary。公共缓存、模型目录和 JIT 目录设置配额与权限，防止一个用户的旧产物污染他人。维护完成后由不同项目运行自己的代表性探针。

Kubernetes GPU 节点的最小方案

集群中要分开管理节点镜像、驱动或 Operator、Container Toolkit、设备插件、工作负载镜像和调度标签。节点 Ready 不等于 GPU 工作负载可用；部署一个只读探针 DaemonSet 或受控 Job，输出设备 UUID、驱动、框架和算子结果。节点池升级先新建小池，使用污点与标签引导 canary，确认监控、日志、MIG 和多卡任务后再迁移。旧节点池在观察期保留，回滚通过重新调度完成，避免在线降级驱动。

离线或受限网络环境

离线环境要提前收集官方包、仓库元数据、镜像、校验值和许可证，而不是复制一台联网机器的整个环境。建立内部镜像和包仓库，记录来源、版本、哈希与批准时间。驱动、Toolkit、框架 wheel 和扩展分别归档，安装脚本只引用内部固定地址。验证时断开外网，确认不会隐式下载编译器、模型或内核。更新流程同样需要漏洞评估、canary 和回滚，不能因离线而永远冻结未知风险版本。

从源码编译框架

源码编译把问题扩大到编译器、构建选项、子模块、架构目标、依赖库和补丁。只有官方二进制不能满足架构、功能或调试需求时才值得承担。冻结源码提交与子模块，保存完整配置、环境和构建日志，产物进入内部仓库并生成 SBOM 或等价依赖清单。构建成功后先跑上游测试，再运行项目探针与基准。不得把一台开发机目录直接复制为生产发布物，也不能省略安全更新路径。

使用第三方 CUDA 扩展

FlashAttention、xFormers、自定义量化或其他扩展常有独立支持矩阵。安装前核对项目官方发行说明、框架版本、Python、编译器、GPU 架构和许可证；优先使用可信来源的版本化 wheel。运行时记录是否实际启用了扩展以及回退实现，因为某些库导入失败后会静默降级。验收既要比较输出与参考实现，也要验证扩展关闭时系统仍能工作或明确失败，避免异常时返回未经关注的慢路径。

做性能基准的公平口径

比较版本时固定输入分布、batch、并发、精度、随机性、预热、同步和测量次数。冷启动包含 JIT、模型加载和缓存建立；稳态执行则排除这些一次性成本，两者分别报告。GPU 时间不能用普通墙钟包围异步调用后直接读取，需按框架方法同步。报告中位数和高分位而非最好一次，并同时保存正确性、峰值显存、功耗或成本边界。微基准的提升只有在端到端任务也改善时才形成发布价值。

做稳定性测试的口径

稳定性不是循环同一短算子几次。按真实任务构造持续时间、并发、输入长度和数据类型，监控温度、功耗、时钟、显存、错误、掉卡与恢复。测试中主动覆盖进程重启、节点重启、容器重建和依赖服务短暂不可用。出现 Xid、ECC 或硬件告警时保留系统日志和设备 UUID，交由硬件或平台流程处理。通过稳定性测试只能证明该时间窗和负载，不代表未来永不失败。

供应链与来源核验

驱动、Toolkit、容器和 Python 包只从官方或组织批准的仓库获取，校验签名或哈希，并记录镜像摘要。搜索结果、论坛附件和网盘中的同名 DLL/SO 不可作为修复来源。依赖扫描发现漏洞后，结合实际可达性、供应商公告和补丁兼容性决定处置，不把扫描计数直接写成已被攻击。内部构建产物也要能追溯源码、构建环境与批准人，撤销时可以定位所有部署位置。

版本台账如何长期维护

把每个工作负载的 GPU 类型、驱动分支、镜像摘要、框架构建、关键扩展、负责人、探针与最后验证时间放入结构化台账。监控官方发行说明只产生候选变更，不能自动覆盖生产。每次变更关联工单、差异、测试、canary、放量与回滚回执；例外项有到期日。台账应从部署系统自动读取可验证字段，人工填写业务边界，避免只靠容易过期的文档。季度复核无人负责、长期未升级和已经退役的组合。

什么时候应停止排错并回滚

如果出现不可解释的数值错误、数据损坏、跨任务普遍回退、频繁驱动重置、无法控制的多卡 hang 或关键安全补丁冲突，应按预先阈值停止扩量。先保护数据和任务队列，再切回已验证节点或镜像；不要在生产峰值继续随机尝试包版本。回滚后仍保存失败环境的镜像、日志和最小复现供离线分析。只有根因、修复和回归都形成证据，才重新进入 canary，而不是因为暂时没再报错就直接全量。

独立任务资产：只读兼容性证据审查器

配套 review-cuda-stack.py 读取一份 JSON 证据文件，检查 GPU、驱动、框架、容器、探针和回滚字段是否齐全，并输出 insufficient_evidence 或 eligible_for_bounded_canary。它不会连接服务器、安装软件、比较最新官方矩阵，也不能证明生产兼容；结论必须与当前官方文档和真实测试共同使用。

怎样从错误回到可验证状态

1. 冻结当前环境信息和完整错误，不先删除包；
2. 用设备、驱动、框架、编译、代表算子五组探针定位层级；
3. 建立干净环境复现，排除个人路径和旧缓存；
4. 只改变一个版本或配置，再跑同一探针；
5. 在小范围真实负载中比较旧基线，保存正确性、时延、显存和失败样本；
6. 确认旧镜像、节点或环境可以恢复后再扩大。

怎样决定“升级驱动”还是“更换框架包”

先看证据落在哪一层。如果驱动低于目标框架或 Runtime 的官方最低要求，并且应用确实需要该构建，驱动升级是候选动作；但要同时核对 GPU、操作系统、云平台和其他共享工作负载。若驱动已满足要求，而错误来自 CPU 构建、错误索引或不受支持的框架 wheel，应修正框架环境，不要触碰宿主驱动。若基础框架正常，只有第三方扩展失败，应优先重建或替换扩展。若问题来自新 GPU 缺少旧二进制架构，则需选择包含目标架构的新构建。任何动作前都保存旧版本与探针，动作后用同一输入复测，不能凭版本数字更大就判定修复。

怎样给“不完全兼容但可运行”写结论

不要写成“兼容”。应明确限定为：在某日期、某 GPU、某驱动、某镜像摘要和某组输入下，哪些探针与业务任务通过；哪些功能、形状、数据类型、多卡路径或长期稳定性尚未验证；是否依赖小版本兼容、forward compatibility、回退实现或临时路径；何时复查、谁负责以及触发回滚的条件。这样读者能区分厂商支持范围、本站观察和编辑判断。只要存在未覆盖的关键路径，状态就应保持受限 canary，而不是扩大到所有生产任务。

哪些证据能证明什么

站内下一步

需要选择 NVIDIA NIM、vLLM 与 TGI 时，可看推理栈选择与迁移指南；需要估算长上下文显存，可看KV 缓存计算与压测；需要把环境变化纳入灰度和回滚，可看AI 模型上线验收清单；需要编写 GPU 内核，可看Triton 分块编程与基准验收。

核验边界：本文没有登录你的服务器、没有修改驱动、没有跑真实模型性能测试，也不承诺任何组合必然兼容。发布日之后的驱动、Toolkit、框架、GPU 和云平台支持变化必须重新核验。