1. 为什么这套组合总在版本上翻车mmdeploy v0.6、mmdetection v2.4、mmcv-full 1.6 这三个包凑在一起是 OpenMMLab 生态里比较经典的一套推理部署组合。它能做的事很明确把 mmdetection 训练出来的检测模型Faster R-CNN、YOLOv3 等通过 mmdeploy 转成 ONNX 或 TensorRT 引擎再用推理 SDK 跑起来。适合谁适合已经跑通训练、准备把模型落到 NVIDIA GPU 或 CPU 上做实际推理的开发者尤其是做工业质检、安防检测这类需要固定推理后端的人。但真正动手时卡人的往往不是模型本身而是版本。mmcv-full 1.6 对 PyTorch 和 CUDA 有硬性要求mmdetection v2.4 又依赖特定 mmcv 版本mmdeploy v0.6 的预编译包还绑定了 CUDA 11.x 和 TensorRT 8.2。三者任意一个版本错位轻则 import 报错重则转换模型时算子注册失败。我试过在 CUDA 11.4 上装 mmcv-full 1.6.0结果编译到一半提示 nvcc 版本不匹配折腾半天才发现是 PyTorch 装成了 CPU 版。这篇就按 Windows/Linux 两条线把环境搭建、settings.json 骨架、以及通过 TaoToken 统一 Key 做接口联调验证串起来。目标是一次性跑通不反复重装。2. TaoToken 前置统一 Key 与 settings.json 骨架在讲 mmdeploy 之前先解决一个容易被忽略的问题推理服务跑起来后怎么统一管理模型调用的 API Key。TaoToken 在这里的角色是一个统一的 API 通道你可以在一个地方拿到 Key然后让不同的推理脚本、Agent 工具、编码助手共用同一套配置不用每个项目单独维护密钥。先到官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册并进入控制台在 API Keys 页面创建一个 Key。拿到 Key 之后不要硬编码在 Python 脚本里而是写进 settings.json让 mmdeploy 的推理服务或你后续的联调脚本统一读取。一个可复制的 settings.json 骨架如下放在项目根目录或用户配置目录都行{ taotoken: { api_base: https://taotoken.net/api, api_key: sk-你的实际Key, default_model: claude-sonnet-4-20250514, timeout: 60, max_retries: 3 }, mmdeploy: { backend: onnxruntime, device: cuda:0, work_dir: ./mmdeploy_models, log_level: INFO }, mmdetection: { config: ./mmdetection/configs/faster_rcnn/faster_rcnn_r50_fpn_1x_coco.py, checkpoint: ./mmdetection/checkpoints/faster_rcnn_r50_fpn_1x_coco.pth } }这个骨架里taotoken 段负责统一 Key 和 API 地址mmdeploy 段控制推理后端和输出目录mmdetection 段指向模型配置和权重。后续无论你是用 Python 脚本调推理还是用命令行工具做转换都从这个文件读参数避免散落各处。注意api_key 不要提交到 Git建议用环境变量覆盖或者把 settings.json 加入 .gitignore。3. 可复制配置从 conda 环境到 mmdeploy 安装3.1 创建环境与安装 PyTorch先建一个干净的 conda 环境Python 版本用 3.8这是 mmcv-full 1.6 和 mmdeploy v0.6 都验证过的版本。conda create -n mmdeploy python3.8 -y conda activate mmdeployPyTorch 版本要和 CUDA 匹配。如果你用 CUDA 11.1装 torch 1.8.1cu111如果用 CUDA 11.3装 torch 1.11.0cu113。下面以 CUDA 11.1 为例pip3 install torch1.8.1cu111 torchvision0.9.1cu111 -i http://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com装完验证一下注意别写成import.__version__那是语法错误import torch print(torch.__version__) print(torch.cuda.is_available())如果cuda.is_available()返回 False说明装成了 CPU 版需要卸载重装对应 CUDA 版本的 wheel。3.2 安装 mmcv-full 1.6.0mmcv-full 1.6.0 是 mmdetection v2.4 和 mmdeploy v0.6 的公共依赖。pip 直接装pip install mmcv-full1.6.0如果 pip 装完 import 报错或者你需要自定义算子可以源码编译git clone https://github.com/open-mmlab/mmcv.git cd mmcv git checkout v1.6.0 MMCV_WITH_OPS1 python -m pip install -e . -v编译完成后跑一下官方检查脚本python .dev_scripts/check_installation.py输出里如果看到mmcv-full is installed successfully说明算子编译没问题。3.3 安装 mmdetection v2.4mmdetection v2.4 的安装依赖 build 工具先装 requirementsgit clone https://github.com/open-mmlab/mmdetection.git cd mmdetection git checkout v2.4.0 pip install -r requirements/build.txt pip install -v -e .装完验证import mmdet print(mmdet.__version__)应该输出 2.4.0。如果报ModuleNotFoundError: No module named mmcv说明 mmcv-full 没装好回到上一步检查。3.4 安装 mmdeploy v0.6 与推理后端mmdeploy v0.6 提供预编译包比源码编译省事。先装 ONNXRuntimepip install onnxruntime1.8.1如果你要用 TensorRT需要从 NVIDIA 官网下载与 CUDA 匹配的 TensorRT 和 cuDNN。以 TensorRT 8.2.3.0、cuDNN 8.2、CUDA 11.4 为例tar -zxvf TensorRT-8.2.3.0.Linux.x86_64-gnu.cuda-11.4.cudnn8.2.tar.gz cd TensorRT-8.2.3.0 python -m pip install python/tensorrt-8.2.3.0-cp38-none-linux_x86_64.whl pip install pycuda然后在~/.bashrc里配置环境变量export TENSORRT_DIR/home/yourname/lib/TensorRT-8.2.3.0 export LD_LIBRARY_PATH${TENSORRT_DIR}/lib:$LD_LIBRARY_PATH export CUDNN_DIR/home/yourname/lib/cuda export LD_LIBRARY_PATH$CUDNN_DIR/lib64:$LD_LIBRARY_PATHsource ~/.bashrc生效后下载 mmdeploy v0.6 的 TensorRT 预编译包wget https://github.com/open-mmlab/mmdeploy/releases/download/v0.6.0/mmdeploy-0.6.0-linux-x86_64-cuda11.1-tensorrt8.2.3.0.tar.gz tar -zxvf mmdeploy-0.6.0-linux-x86_64-cuda11.1-tensorrt8.2.3.0.tar.gz cd mmdeploy-0.6.0-linux-x86_64-cuda11.1-tensorrt8.2.3.0 python -m pip install dist/mmdeploy-0.6.0-py38-none-linux_x86_64.whl python -m pip install sdk/python/mmdeploy_python-0.6.0-cp38-none-linux_x86_64.whl最后把 SDK 的 lib 路径加进环境变量export LD_LIBRARY_PATH/path/to/mmdeploy-0.6.0-linux-x86_64-cuda11.1-tensorrt8.2.3.0/sdk/lib:$LD_LIBRARY_PATHWindows 下把.whl换成对应 win_amd64 版本环境变量用系统设置里的 Path 添加逻辑一样。4. 验证请求模型转换与 TaoToken 连通性联调4.1 转换 Faster R-CNN 到 ONNX环境装好后先用 ONNX 后端跑一遍转换确认 mmdeploy 能正常调用 mmdetection 的模型配置。git clone --recursive https://github.com/open-mmlab/mmdeploy.git python -m pip install -r mmdeploy/requirements/runtime.txt cd mmdetection/checkpoints wget https://download.openmmlab.com/mmdetection/v2.0/faster_rcnn/faster_rcnn_r50_fpn_1x_coco/faster_rcnn_r50_fpn_1x_coco_20200130-047c8118.pth -O faster_rcnn_r50_fpn_1x_coco.pth cd ../../mmdeploy mkdir -p mmdeploy_models/faster_rcnn python tools/deploy.py \ configs/mmdet/detection/detection_onnxruntime_dynamic.py \ ../mmdetection/configs/faster_rcnn/faster_rcnn_r50_fpn_1x_coco.py \ ../mmdetection/checkpoints/faster_rcnn_r50_fpn_1x_coco.pth \ ../mmdetection/demo/demo.jpg \ --work-dir mmdeploy_models/faster_rcnn/ \ --device cpu \ --dump-info如果日志最后出现All process success说明转换成功。转换过程中会看到大量 TracerWarning比如Converting a tensor to a Python boolean might cause the trace to be incorrect这些是 ONNX 导出时的正常提示不影响结果。但如果你看到The shape inference of mmdeploy::MMCVDeformConv2d type is missing说明自定义算子没注册上需要检查 mmdeploy 的 ops 是否编译进环境。4.2 用 TaoToken 统一 Key 做接口连通性验证模型转换成功后写一个 Python 脚本从 settings.json 读 TaoToken 配置调用模型对话接口做一次连通性验证。这一步的目的是确认你的 Key 和 API 通道是通的后续可以把推理结果或日志通过这个通道做进一步处理。import json import requests with open(settings.json, r) as f: cfg json.load(f) api_base cfg[taotoken][api_base] api_key cfg[taotoken][api_key] model cfg[taotoken][default_model] headers { Authorization: fBearer {api_key}, Content-Type: application/json } payload { model: model, messages: [ {role: user, content: mmdeploy v0.6 转换 ONNX 成功请回复 OK} ], max_tokens: 32 } resp requests.post(f{api_base}/v1/chat/completions, headersheaders, jsonpayload, timeout60) print(resp.status_code) print(resp.json())如果返回 200 并且内容里有 OK说明 TaoToken 通道正常。如果返回 401检查 Key 是否复制完整如果返回 404检查 api_base 是否写成了https://taotoken.net/api而不是带其他路径。4.3 推理 SDK 调用验证转换后的模型可以用 mmdeploy 的推理 SDK 直接跑from mmdeploy_runtime import Detector import cv2 detector Detector( model_pathmmdeploy_models/faster_rcnn/end2end.onnx, device_namecpu ) img cv2.imread(../mmdetection/demo/demo.jpg) bboxes, labels, masks detector(img) print(f检测到 {len(bboxes)} 个目标)如果输出检测框数量大于 0说明整条链路从 mmdetection 模型到 mmdeploy 推理都通了。5. 本篇常见错排查5.1 mmcv-full 编译报 nvcc 版本不匹配现象是RuntimeError: CUDA error: no kernel image is available for execution或者编译时提示nvcc fatal: Unsupported gpu architecture。原因是 PyTorch 的 CUDA 版本和系统 nvcc 版本不一致。解决办法是用nvcc --version和torch.version.cuda对比确保两者主版本一致。如果不一致要么重装 PyTorch要么在编译 mmcv 时指定TORCH_CUDA_ARCH_LIST。5.2 mmdeploy 转换时 MMCVDeformConv2d 未注册日志里反复出现The shape inference of mmdeploy::MMCVDeformConv2d type is missing模型虽然能转出来但推理结果可能不对。这是因为 mmdeploy 的自定义算子没有正确链接。检查两点一是 mmcv-full 是否用MMCV_WITH_OPS1编译二是 mmdeploy 的预编译包版本是否和 CUDA 版本匹配。如果用的是 CPU 版 ONNXRuntimeDeformConv 会走 PyTorch 原生实现不会触发这个警告。5.3 import mmdet 报cannot import name digit_version这是 mmcv 版本和 mmdetection 版本不匹配的典型报错。mmdetection v2.4 要求 mmcv-full 在 1.3.8 到 1.6.0 之间如果你装了 mmcv 2.x就会报这个错。卸载重装pip uninstall mmcv mmcv-full -y pip install mmcv-full1.6.05.4 TaoToken 请求返回 403 或超时先确认 settings.json 里的 api_key 没有多余空格再确认 api_base 是https://taotoken.net/api。如果公司网络有出口限制检查是否能正常访问该域名。超时的话把 timeout 从 60 调到 120 试试。5.5 Windows 下 TensorRT 环境变量不生效Windows 下LD_LIBRARY_PATH不适用需要把 TensorRT 的 lib 目录和 cuDNN 的 bin 目录加到系统 Path 里然后重启终端。另外 Windows 的预编译包命名是win_amd64别下成 Linux 版。6. 后续联调与 Key 管理建议环境跑通之后建议把 settings.json 里的 mmdeploy 段和 taotoken 段分开管理。mmdeploy 的配置跟着项目走taotoken 的 Key 用环境变量注入这样换机器或换项目时不用改代码。如果你后续要做长期的编码辅助或 Agent 集成可以到 Coding Plan 页面看看适合的套餐如果只是临时验证模型对话直接用模型对话入口就行。接入文档里有完整的 API 参数说明排障时对照着看能省不少时间。