LingBot-Vision 在 mac 上部署的 GPU 加速无效的排查路径

LingBot-Vision 在 mac 上出现 GPU 加速无效，和 NVIDIA 平台的 CUDA 问题不太一样。多数情况下，代码没有报错，但计算仍走 CPU。排查时不要先改模型代码，而要先确认框架、计算后端和实际运行设备这三层中间是哪一层断开了。

LingBot-Vision 在 mac 上 GPU 加速无效，通常不是某个单一配置缺失，而是推理框架未启用 Metal 后端、Python 依赖未装对应支持包、或者调用代码没有把输入数据放到 GPU 设备上这三层问题叠加。排查顺序建议是：先确认框架支持哪种 mac 加速后端，再核对安装的依赖，最后用一个固定输入跑通日志验证；在旧版本依赖和 Intel mac 上，可能需要直接放弃 GPU 加速。

在 mac 上，不同推理框架的加速路径不同。PyTorch 走 MPS（Metal Performance Shaders），ONNX Runtime 走 CoreML 执行器，MLX 是 Apple 生态中面向 Apple Silicon 的框架。LingBot-Vision 到底依赖哪一条，要先从项目依赖或模型加载入口确认，不要凭印象去装包。

先确认推理框架在 mac 上的加速后端

打开 LingBot-Vision 的模型目录，查看 requirements.txt 或调用入口里 import 了哪些包。常见的三个方向是 torch、onnxruntime、mlx。如果入口是 transformers + torch，就要走 MPS 排查；如果目录里有 .mlpackage 或 coreml 相关代码，则要检查 Core ML 模型输出。

如果使用 PyTorch，先确认当前环境里的 torch 是否能识别 Mac GPU：

python -c "import torch; print(torch.backends.mps.is_available())"

返回 False 时，优先确认 macOS 版本是否高于 12.3，以及 PyTorch 是否为 Apple Silicon 版本。更早的 PyTorch 版本对 MPS 的支持不完整，需要先升级。如果 LingBot-Vision 的环境文件锁定了固定版本，升级前先做一次模型推理备份。

检查代码里是否真的用了 GPU 设备

常见情况是环境已经支持 MPS，但推理代码仍把所有 tensor 留在 CPU。以 PyTorch 推理为例，加速是否生效取决于模型、输入和中间输出是否都放到了 mps 设备上：

device = "mps" if torch.backends.mps.is_available() else "cpu"
model = model.to(device)
x = torch.randn(1, 3, 224, 224).to(device)
with torch.no_grad():
    out = model(x)

如果你的 LingBot-Vision 启动脚本里有 device 或 device_map 这类参数，直接改成 mps 往往还不够。数据加载、滑动窗口、后处理等环节如果创建了新 tensor，默认仍在 CPU 上，容易反复产生 CPU 与 GPU 拷贝。这一点只能逐段检查，没有通用开关。

在活动监视器之外验证加速是否生效

macOS 自带的活动监视器可以看 GPU 历史记录，但集成显卡的占用观测不明显，短推理可能完全看不到波峰。更可靠的方法是在推理循环里把单次耗时打印出来，多跑几次取稳定值，再和 CPU 模式对比。

import time

start = time.perf_counter()
for _ in range(5):
    with torch.no_grad():
        out = model(x)
torch.mps.synchronize() if device == "mps" else None
print(time.perf_counter() - start)

注意 torch.mps.synchronize() 只对 PyTorch 的 MPS 后端有效。如果 LingBot-Vision 使用 ONNX Runtime，执行器名称不同，需要在会话配置里显式启用 CoreML。如果使用 MLX，则要确认模型参数是通过 mx.array 参与计算。

旧依赖、Intel mac 与可疑的 fallback

如果你正在 Intel Mac 上部署，需要重新评估 GPU 加速的实际收益。MPS 对 Intel 的支持范围有限，可能出现“应用没报错，但速度没有变化”的情况。这时可以先回到 CPU 模式，确认模型本身能跑通，再决定是否维持 GPU 尝试。

另一个容易被忽视的点是：即使启用 MPS，自定义算子不一定都能在 MPS 上执行。PyTorch 遇到不支持的算子会自动 fallback 到 CPU，如果你只观察单次总耗时，会误以为 GPU 完全无效。建议先用一个简单网络验证环境加速能力，再用 LingBot-Vision 的真实模型测试。如果真实模型和自定义算子深度耦合，GPU 可能只覆盖了部分网络层。

最后，不要因为已经设置了 device 而忽略日志输出。在模型推理入口处打印最终使用的 device 名称，并在第一次推理时观察 CPU 和 GPU 是否有明显告警；如果遇到“not implemented”提示，说明该算子尚未打通 MPS 路径，这是框架支持问题。