快速诊断 AI Agent 的 CUDA 兼容性

本地 AI Agent 的部署失败，绝大多数时候不是模型选型或 Prompt 设计的问题，而是环境层面的隐性冲突。其中 CUDA 兼容性又是最容易被误判的一环：表面症状是“装上了但用不了 GPU”、进程能起但算力落回 CPU，或者推理时出现 offloading 异常，很多人第一反应是重装驱动或整个系统，实际上问题往往出在驱动、CUDA 运行时与机器学习框架三者没有处于同一套兼容关系里。

诊断 CUDA 兼容性，核心思路是把“隐式不兼容”变成可核对的清单，而不是凭感觉换包。第一步先确认本机可见的 GPU 设备，这一步在系统层面就能完成，如果设备本身不可见，后续所有框架层面的排查都没有意义。第二步核对当前生效的 CUDA 路径，注意系统里可能存在多套 CUDA，环境变量指向的未必是实际使用的那一套。第三步才是检查 Python 环境里实际加载的框架版本——PyTorch、Transformers 这类库各自对应特定的 CUDA 运行时版本，装对了驱动但框架编译时针对的是另一套 CUDA，同样无法真正调用 GPU。

这里有一个常见误区：很多人以为“装了 CUDA”就等于“CUDA 可用”。实际上驱动、CUDA 工具包、框架内置的 CUDA 运行时是三个不同层次的东西。驱动由系统管理，CUDA 工具包服务于编译场景，而大多数机器学习框架自带或依赖独立的 CUDA 运行时。判断兼容性的关键，不是看系统里装了什么，而是看框架实际加载的是哪一套。社区里已有专门面向 Python、CUDA 与常见 ML 框架兼容检查的技能型工具思路，其价值正在于此：把分散在多个层次的状态汇总成一份可核对的清单，避免逐个猜测。

诊断路径明确之后，预防比修复更重要。安装顺序上，应当先把包管理器与构建相关基础组件更新到位，再安装数值与数学基础库，最后安装 Agent 框架主体。这个顺序一旦颠倒，先装主程序再补底层依赖，很容易把已经解析好的依赖树打乱，产生难以定位的隐性问题。同时务必使用独立虚拟环境，避免系统 Python、全局 site-packages 与项目环境混用——同一台机器上多个 Agent 项目共用一个全局环境，几乎必然在后续升级时互相拖垮。

如果安装阶段就失败，九成与依赖顺序、权限或网络拉取有关，回到虚拟环境或容器重建通常比继续“补丁式安装”更省时间。如果安装成功但 GPU 不生效，优先回到驱动可见性与框架—CUDA 组合这一层核对，而不是先改 Agent 的业务 Prompt。一个值得注意的细节是：可用显存明显小于标称总量时，模型与中间状态很容易顶满，这时优先降低同时驻留的大组件，再考虑更换更重的模型，而不是怀疑 GPU 本身损坏。

CUDA 兼容性只是本地 Agent 环境冲突的一类，但它最具迷惑性，因为报错信息往往含糊，且涉及多个层次的状态叠加。把这一层先关掉，后续的 Python 依赖、运行时栈、扩展连接排错才有稳定的地基。固定一条部署主线，用最小配置跑通主循环，再逐项排查扩展面，这条路径比反复重装系统可靠得多。