FastAPI部署Ultralytics YOLOv8遇NameError及OpenCV断言错误求助

核心错误关联说明 #

表面的NameError: predictions is not defined是衍生问题——因为model.predict()内部触发OpenCV的断言崩溃，导致predictions变量未完成赋值，后续代码引用时才会抛出这个错误。重点要解决底层的OpenCV断言失败。

具体排查方向 #

• 检查输入图像的有效性
  即便你确认预处理流程无问题，仍需验证：

  • 图像是否为空（比如预处理后数组维度为0，或processed_image为None）
  • 图像通道数是否符合要求：YOLOv8默认需要3通道RGB图像，单通道灰度图或异常通道顺序（如未转换的BGR）可能触发边界处理断言失败
  • 图像尺寸是否合法：宽高不能为0，且不能小于YOLOv8最小输入尺寸（如64x64）

• 验证预处理后图像的格式与类型

  • 确认processed_image是numpy.ndarray类型，而非PIL Image或其他格式（Ultralytics虽支持多输入，但边缘情况可能导致转格式出错）
  • 检查数组数据类型：必须是uint8，浮点型（如0-1的float32）会触发OpenCV的copyMakeBorder断言错误
  • 确认维度顺序：需为(H, W, C)的HWC格式，(C, H, W)的CHW格式会导致内部处理异常

• 排查库版本兼容性
  部分旧版Ultralytics与特定OpenCV版本存在冲突，比如YOLOv8 8.0.x与OpenCV 4.5.x组合可能触发边界处理错误。可尝试升级/降级库：

  pip install --upgrade ultralytics opencv-python
  

  或指定稳定版本组合：

  pip install ultralytics==8.0.200 opencv-python==4.8.0.76
  

• 检查预测参数设置

  • 确认predict()的参数无异常：比如imgsz设置过小、padding参数配置错误，手动指定的尺寸与图像实际尺寸不匹配且开启pad时，易触发边界处理错误
  • 先用默认参数测试，排除参数干扰：

    predictions = model.predict(source=processed_image, imgsz=640, pad=0.5)
    

• 隔离FastAPI请求流程的影响

  • 如果是从上传文件读取图像，需确认文件读取完整：比如用PIL.Image.open()读取上传文件时，是否因文件损坏、传输不完整导致图像数据异常
  • 脱离FastAPI单独测试：用本地图像直接调用model.predict()，验证模型本身是否能正常运行，排除请求处理环节的问题

内容的提问来源于stack exchange，提问作者J.c