English | 简体中文

🚀 YOLO Flutter - Ultralytics 官方插件

Ultralytics YOLO Flutter 是官方 Flutter 插件，用于在 iOS 和 Android 应用中运行 YOLO 模型。它在两个平台上支持目标检测、实例分割、语义分割、单目深度估计、图像分类、姿态估计和旋转框检测，提供两种核心用法：

• YOLO：单张图片推理
• YOLOView：实时相机推理

这个插件的目标很直接：要么使用官方模型 ID，要么把你自己的导出模型丢进应用里，让插件自动解析任务元数据。

✨ 功能特性

• Ultralytics 官方插件
• 一套 Dart API 同时覆盖 Android 和 iOS
• 基于元数据加载模型，并内置官方模型下载与缓存
• 同时支持实时相机推理和单图推理
• 提供阈值、加速器选择与结果流式传输等控制项
• 支持 YOLO26 和 YOLO11 系列模型

功能	Android	iOS	说明
目标检测	✅	✅	边界框、类别和置信度
实例分割	✅	✅	实例掩膜、边界框和类别
语义分割	✅	✅	每个像素的密集类别掩膜
单目深度估计	✅	✅	提供官方 LiteRT 和 Core ML 模型
图像分类	✅	✅	Top-1/Top-5 类别预测和分数
姿态估计	✅	✅	关键点、边界框和置信度
旋转框（OBB）检测	✅	✅	旋转框和多边形角点
实时相机推理	✅	✅	使用 YOLOView 构建实时相机场景
单图推理	✅	✅	使用 YOLO 处理图片字节
官方模型	✅	✅	内置模型 ID 发现、下载和缓存
自定义模型	✅	✅	Android 用 LiteRT（TFLite），iOS 用 Core ML，并优先读取元数据
高通 NPU（QNN）	✅	—	在 Snapdragon 上为 *_qnn.onnx 模型可选启用 Hexagon NPU 推理

⚡ 快速开始

安装插件：

插件地址：https://pub.dev/packages/ultralytics_yolo

dependencies:
  ultralytics_yolo: ^0.7.1

flutter pub get

先用默认官方模型跑起来：

import 'package:ultralytics_yolo/ultralytics_yolo.dart';

final modelId = YOLO.defaultOfficialModel() ?? 'yolo26n';

YOLOView(
  modelPath: modelId,
  onResult: (results) {
    for (final r in results) {
      debugPrint('${r.className}: ${r.confidence}');
    }
  },
)

单图推理示例：

final yolo = YOLO(modelPath: 'yolo26n');
await yolo.loadModel();
final results = await yolo.predict(imageBytes);

▶️ 示例应用 | 📖 安装指南 | ⚡ 快速开始文档

从 Ultralytics Platform 导入模型

在模型的 Export 选项卡中，点击已完成的 LiteRT 导出（iPhone 使用 Core ML 导出）上的二维码按钮，然后打开应用，点击底部工具栏中的二维码按钮，并将当前相机预览对准二维码。扫码时相机画面会在取景框外变暗；点击 Cancel 或再次点击二维码按钮即可恢复实时推理。Android 使用 FP32 或 W8A32 精度的 LiteRT，iPhone 使用 Core ML；导出必须使用 batch 1 和静态输入形状。示例应用会先显示模型信息，经确认后下载，并将模型添加到 Models 选择器，支持选择、删除和离线使用。点击当前模型名称，即可选择 Custom 自定义导入模型，或在按任务排列的紧凑行中选择任意 Official 官方模型的尺寸。顶部在模型名称上方显示任务，并为导入模型标注 Custom。Custom 分组还提供 Scan QR 行，以及打开 Platform 导出指南的帮助按钮。Core AI 导入链接在原生 iOS 应用中打开。

导入链接在 24 小时内授权下载单个导出。任何获得链接的人都可以在有效期内下载，已安装的模型在链接过期后仍可使用。每个导出独立安装，名称相同也不会覆盖。应用链接由示例应用处理；插件的解析器和模型选择器仍可使用您自己的下载来源。

📦 模型加载方式

插件支持三种模型来源。

1. 官方模型 ID

可直接使用默认官方模型，或传入指定官方 ID，例如 yolo26n：

final yolo = YOLO(modelPath: YOLO.defaultOfficialModel() ?? 'yolo26n');

可通过 YOLO.officialModels() 查看当前平台可用的全部官方 ID。官方资产在首次使用时自动下载并缓存到应用存储，因此应用安装包不携带大体积模型文件。

官方资产以 GitHub release 资产的形式维护：

平台	运行时资产	Release
Android	LiteRT w8a32 .tflite	yolo-flutter-app v0.7.0
Android NPU（可选）	QNN *_v73/_v81_qnn.onnx	yolo-flutter-app v0.7.0
iOS	Core ML int8 .mlpackage.zip	yolo-ios-app v8.3.0

Flutter 解析器在 Android 上使用 TFLite release，在 Apple 平台上使用 Core ML release。这些 release 标签被刻意固定，以保证首次下载可复现。官方导出矩阵、URL 模式与模型属性详见模型指南。

Core ML（.mlpackage）仍是默认格式。Core AI（.aimodel）是面向 iOS 27 及更高版本设备的可选项：传入 .aimodel 路径、.aimodel.zip Flutter 资源或 .aimodel.zip URL 即可启用。更早的 iOS 版本和 iOS 模拟器不支持 Core AI。Ultralytics iOS 应用在“设置”中提供同样的可选开关（默认关闭）。官方可选资产是 yolo-ios-app v8.3.0 release 上的 .aimodel.zip 文件；取舍详见 yolo-ios-app 性能记录。

final yolo = YOLO(modelPath: 'https://github.com/ultralytics/yolo-ios-app/releases/download/v8.3.0/yolo26n.aimodel.zip');

2. 你自己的导出模型

传入你自己的导出 YOLO 模型本地路径或 Flutter 资源路径：

final yolo = YOLO(modelPath: 'assets/models/my-finetuned-model.tflite');

如果导出的模型包含内嵌元数据，插件会自动推断 task 和类别标签——它会读取 Ultralytics 的附加 ZIP（appended-ZIP）元数据，并以标准 TFLite（FlatBuffers）元数据作为回退——因此直接拖入的自定义模型可以自动识别。如果缺少元数据，请显式传入 task。

final yolo = YOLO(
  modelPath: 'assets/models/my-finetuned-model.tflite',
  task: YOLOTask.detect,
);

3. 远程模型 URL

传入 http 或 https URL，插件会先下载到应用存储，再完成加载。

4. 高通 NPU 模型（Android，可选启用）

Android 默认使用 LiteRT（TFLite），这一点保持不变——现有应用无需任何改动，QNN 支持也不会给你的构建增加任何体积。任何以 _qnn.onnx 结尾的模型路径（通过 yolo export model=yolo26n.pt format=qnn nms=None imgsz=640 导出，分类任务使用 imgsz=224）都会改由 ONNX Runtime QNN Execution Provider 路由到 Hexagon NPU 上运行。请使用 ultralytics>=8.4.188 导出：更早的版本在 onnxruntime-qnn 2.4 或更新版本下生成的上下文二进制在此无法加载，并报错 Input name not found。nms=None 选择原始一对多输出，由 Android 端执行 NMS。

运行 QNN 模型需要配备 Hexagon HTP 的 Snapdragon 设备（官方 _v73 资产要求 Snapdragon 8 Gen 2 或更新；_v81 面向 Snapdragon 8 Elite Gen 5），并在应用的 android/app/build.gradle 中添加三处配置：

android {
    packagingOptions {
        jniLibs {
            useLegacyPackaging = true // Hexagon DSP 加载器需要真实的 .so 文件，而非 APK 内存映射
        }
    }
}

dependencies {
    implementation 'com.microsoft.onnxruntime:onnxruntime-android-qnn:1.29.0'
    implementation 'com.qualcomm.qti:qnn-runtime:2.51.0' // 比 AAR 自带的 QAIRT 更新；最新的 Snapdragon 芯片需要
}

final yolo = YOLO(
  modelPath: 'https://github.com/ultralytics/yolo-flutter-app/releases/download/v0.7.0/yolo26n_v73_qnn.onnx',
  task: YOLOTask.detect,
);

未添加上述 Gradle 配置时，加载 _qnn.onnx 模型会返回明确的错误信息，TFLite 模型不受影响。随附的示例应用同样采用此可选启用方式——默认不包含 QNN 运行时以保持较小的下载体积，如需在设备上测试 NPU 路径，请使用 ENABLE_QNN=1 构建（例如 ENABLE_QNN=1 flutter run --release）。CPU/GPU/NPU 实测数据与调优说明见性能指南。

🧭 官方模型还是自定义模型

场景	推荐方式
想最快跑通接入	使用官方模型 ID，例如 yolo26n
你训练或导出了自己的模型	使用自定义资源或本地文件
不同客户或环境需要不同模型	使用远程 URL
希望插件自动推断 task	使用带元数据的导出模型
你的导出模型没有元数据	自定义模型并显式传入 task

官方模型可直接从 YOLO.defaultOfficialModel() 或 YOLO.officialModels() 开始；自定义模型则直接从你准备实际交付的导出文件开始。

📥 使用你自己的模型

对于自定义模型，应用侧配置应尽量简单：

• Android 原生资源：把 .tflite 放到 android/app/src/main/assets
• Android Flutter 资源：把 .tflite 放到 assets/models/
• iOS 工程资源：把 .mlpackage 或 .mlmodel 拖进 ios/Runner.xcworkspace
• iOS Flutter 资源：把 .mlpackage.zip 放到 assets/models/

然后把对应路径传给 modelPath 即可。

官方资产维护

Android TFLite release 资产由 scripts/export-tflite-models.py 生成。该脚本定义了官方 YOLO26 任务/尺寸矩阵、w8a32 导出设置（int8 权重、FP32 激活——动态范围量化，无需校准数据）、可选的一次性 TFLite 推理验证，以及可选的 GitHub release 上传。

请在 Linux x86 或 macOS 上使用 Python ≥3.10 运行：

uv venv --python 3.12 .venv
uv pip install --torch-backend cpu "ultralytics-opencv-headless[export-litert]>=8.4.188"
uv run python scripts/export-tflite-models.py --verify

使用 --upload --repo ultralytics/yolo-flutter-app --tag v0.7.0 替换现有 .tflite 资产。QNN 使用 Ultralytics 按相同的任务 imgsz 导出；Core ML 资产由 ../yolo-ios-app/scripts/export-models.py 生成，并替换 iOS v8.3.0 release 上的现有资产。所有移动端资产的固定输入尺寸统一为：分类任务 224 × 224，其余任务 640 × 640。

Android 推理运行在 LiteRT 2.x 之上，带有自动的 GPU -> CPU 加速器降级链。w8a32 资产作为官方下载产物（最小的可在 GPU 上编译的 litert 格式）；在受支持的设备上，GPU delegate 会编译整个计算图，否则回退到 CPU。GPU 覆盖仍取决于设备驱动和计算图，因此请在目标硬件上确认 delegate 的放置（GPU delegate 以 FP16 运行计算图）：

# Requires ultralytics>=8.4.142
from ultralytics import YOLO

YOLO("yolo26n.pt").export(format="litert", nms=None, imgsz=640)
# 分类模型使用 imgsz=224。

🎯 该用哪个 API

如果你已经拿到了图片字节并且只想做单次推理，用 YOLO：

final yolo = YOLO(modelPath: 'yolo26n');
await yolo.loadModel();
final results = await yolo.predict(imageBytes);

如果你要做实时相机推理，用 YOLOView：

final controller = YOLOViewController();

YOLOView(
  modelPath: 'yolo26n',
  controller: controller,
  onResult: (results) {},
)

await controller.switchModel('assets/models/custom.tflite', YOLOTask.detect);

如果你想要完整的 Ultralytics 相机 UI，用 YOLOShowcase：

YOLOShowcase(
  initialTask: YOLOTask.detect,
  initialModelSize: 'n',
  onCapture: (bytes) {},
)

🔄 从 0.3.x UI API 迁移

0.4.0 版本移除了旧的 Dart 侧叠层/控件层。相机检测结果现在由 YOLOView 原生渲染；Flutter 仅负责周围的应用控件。

已移除的 0.3.x API	0.4.0 替代方案
YOLOOverlay, YOLOOverlayTheme	删除这些 widget。使用原生 YOLOView 叠层，或通过 onResult/YOLO.predict() 自行渲染。
YOLOControls	使用 YOLOShowcase 获取完整 UI，或直接组合导出的 Material widget。
YOLOView.showNativeUI	使用 YOLOShowcase 获取内置控件；使用裸 YOLOView 自行构建 UI。
YOLOView.showOverlays, YOLOView.overlayTheme	无构造参数替代。相机叠层绘制为原生实现，不再从 Dart 侧控制主题。
YOLOViewController.setShowUIControls()	在 YOLOView 外侧自行显示/隐藏 Flutter 控件。
YOLOViewController.setShowOverlays()	仍然可用：切换原生叠层渲染。capturePhoto(withOverlays: false) 仅影响捕获的 JPEG 输出。

🧩 推荐接入模式

应用类型	推荐模型加载方式
实时相机场景	YOLOView(modelPath: 'yolo26n')
图库或单图推理流程	YOLO(modelPath: 'yolo26n')
应用内置自定义模型	YOLO(modelPath: 'assets/models/custom.tflite')
同时支持 Core ML 与 TFLite 的跨平台应用	使用各平台对应导出文件，并让元数据决定 task
运行时动态切换模型	YOLOViewController.switchModel(...)

📚 文档

指南	说明
安装指南	环境要求与平台配置
快速开始	最短路径跑通第一个示例
模型指南	官方模型、自定义模型、导出流程
使用指南	常见应用模式与示例
API 参考	完整 API 文档
性能优化	性能调优、控制项与设备实测记录
故障排查	常见问题与修复方法

🤝 社区与支持

• 💬 有问题？ Discord | Forums | GitHub Issues
• 🐛 发现 bug？ 在这里提交
• 💡 想提功能建议？ 欢迎告诉我们

💡 参与贡献

Ultralytics 的成长离不开社区协作，我们非常重视你的贡献。无论是修复 bug、增强功能还是改进文档，你的参与都非常重要。请查看我们的贡献指南以了解如何参与，也欢迎通过问卷分享你的反馈。衷心感谢所有贡献者的支持！🙏

📄 许可证

Ultralytics 提供两种许可证，以适应不同需求：

• AGPL-3.0 License：适合学生、研究人员以及热衷于开源协作的开发者。这是一个经 OSI 批准的许可证，鼓励知识共享和开放贡献。详情请参阅 LICENSE 文件。
• Enterprise License：适用于商业应用，允许将 Ultralytics 软件和 AI 模型无缝集成到商业产品与服务中，而无需遵守 AGPL-3.0 的开源要求。如有商业使用需求，请了解企业许可证。

🔗 相关资源

原生 iOS 开发

如果你希望在 iOS 应用中直接使用 YOLO 模型与 Swift 集成，而不是通过 Flutter，可以查看我们的专用 iOS 仓库：

👉 Ultralytics YOLO iOS App - 一个原生 iOS 应用，演示如何使用 Ultralytics YOLO 模型进行实时目标检测、实例分割、语义分割、深度估计、图像分类、姿态估计和旋转框检测。

该仓库提供：

• 面向 iOS 的纯 Swift 实现
• 直接的 Core ML 集成
• 原生 iOS UI 组件
• 多种 YOLO 任务的示例代码
• 针对 iOS 性能的优化

[!NOTE] 在 iOS 上，本插件构建于共享的 UltralyticsYOLO Swift 包（import UltralyticsYOLO）之上——与原生 iOS 应用使用同一推理核心——两者通过单一事实来源保持同步。插件的 iOS 源代码（ios/ultralytics_yolo/）仅包含 Flutter 桥接层和相机/视图组件，并同时面向 Swift Package Manager 和 CocoaPods 发布。

📮 联系方式

如果你在使用 Ultralytics YOLO 时遇到问题，或有功能建议，请通过 GitHub Issues 提交。若想参与更广泛的讨论、提问或获取社区支持，欢迎加入我们的 Discord 服务器。