# yolov11

**Repository Path**: ybli_code/yolov11

## Basic Information

- **Project Name**: yolov11
- **Description**: The simplest way to train YOLOv11
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 25
- **Forks**: 8
- **Created**: 2025-05-29
- **Last Updated**: 2026-10-08

## Categories & Tags

**Categories**: cv

**Tags**: yolov11

## README

# YOLOv11

大道至简，仅需三行代码训练 YOLOv11。同时支持将模型部署到 Android，实现实时视频识别。

## 目录

- [Python 端：训练与推理](#python-端训练与推理)
- [Android 端：实时视频识别](#android-端实时视频识别)
- [项目结构](#项目结构)

---

## Python 端：训练与推理

### 配置教程

- 克隆项目
```
git clone https://github.com/li-yibing/yolov11.git
```
国内加速链接：
```
git clone https://gitee.com/ybli_code/yolov11.git
```

- 安装依赖
```shell
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
```

- 推理图像
```shell
python predict.py
```
推理结果：
![su7.jpg](res/su7.jpg)

- 训练模型

删除 datasets 文件夹，替换为自己的 datasets 文件夹。格式参考：
![数据集样式](res/datasets.png)

如果你没有自己的数据集可以下载样例：
1. PCB缺陷检测 https://pan.baidu.com/s/13GO34J1NVL9jNhc3j8frHQ?pwd=ybli
2. 国际象棋目标检测  https://pan.baidu.com/s/13OWELnbb9beQlvtTaUYkxA 提取码: ybli 

```shell
python train.py
```
训练日志：
![train.png](res/train.png)

- 验证模型
```shell
python test.py
```
验证日志：
![val.png](res/val.png)

---

## Android 端：实时视频识别

将 YOLOv11 模型部署到 Android，通过相机实时识别视频流中的目标。技术方案：**TFLite + CameraX + Kotlin**。

### 架构总览

```
PyTorch (.pt)  ──导出──>  TFLite (.tflite)  ──部署──>  Android App
   yolo11n.pt              yolo11n_320.tflite          实时视频识别
```

### 性能基准（红米 K70 Pro，骁龙 8 Gen 3）

| 模型 | 输入尺寸 | 后端 | 帧率 (FPS) | 精度 |
|------|---------|------|-----------|------|
| yolo11n.pt | 640×640 | PyTorch CPU | N/A（参考） | 100% |
| FP32 | 640×640 | TFLite GPU | 1.2 | ≈100% |
| FP32 | 320×320 | TFLite GPU | 15.1 | ≈99% |
| INT8 | 320×320 | TFLite auto（NNAPI/GPU） | 15+ | ≈97% |

模型导出的张量约定（已通过 Python 脚本验证）：

| 项目 | 形状 | 说明 |
|------|------|------|
| 输入 | `[1, 320, 320, 3]` float32 | NHWC, RGB, 归一化到 [0, 1] |
| 输出 | `[1, 84, 2100]` float32 | 前 4 通道为 cx/cy/w/h（**归一化坐标 [0,1]**），后 80 通道为类别置信度（**已 sigmoid**） |

### 第一步：导出 TFLite 模型

```shell
# 默认：导出 yolo11n.pt 到 640×640（兼容性最好）
python export_tflite.py

# 推荐：导出 320×320（移动端实时识别最佳选择，速度 4 倍提升）
python export_tflite.py --imgsz 320

# 进一步加速：INT8 量化（体积更小、速度更快，精度略降）
python export_tflite.py --imgsz 320 --int8

# 指定自定义训练的模型
python export_tflite.py --model runs/detect/train/weights/best.pt --imgsz 320
```

导出完成后会在 `export/` 目录下生成：
- `yolo11n_tflite.tflite`：FP32 模型（640×640）
- `yolo11n_320_tflite.tflite`：FP32 模型（320×320）
- `yolo11n_320_int8_tflite.tflite`：INT8 量化模型（320×320，推荐）
- `labels.txt`：类别标签（自动从模型元数据提取）

### 第二步：Android 工程结构

```text
android/
├── app/
│   ├── src/main/
│   │   ├── assets/
│   │   │   ├── yolo11n.tflite            # FP32 640×640 模型
│   │   │   ├── yolo11n_320.tflite         # FP32 320×320 模型
│   │   │   ├── yolo11n_320_int8.tflite    # INT8 量化模型（推荐）
│   │   │   └── labels.txt                 # COCO 80 类标签
│   │   ├── java/com/yolov11/detector/
│   │   │   ├── MainActivity.kt           # 入口，权限申请、异步推理、后端切换
│   │   │   ├── CameraManager.kt           # CameraX 封装：预览 + 帧分析
│   │   │   ├── YoloV11Detector.kt         # TFLite 推理封装（GPU/NNAPI/CPU 多后端）
│   │   │   ├── OverlayView.kt             # 检测框绘制（Matrix 变换）
│   │   │   └── Detection.kt               # 检测结果数据类
│   │   ├── res/                           # 布局/字符串/主题/图标
│   │   └── AndroidManifest.xml
│   ├── build.gradle.kts
│   └── proguard-rules.pro
├── gradle/wrapper/                        # Gradle Wrapper 8.14
├── build.gradle.kts
├── settings.gradle.kts
└── gradle.properties
```

### 第三步：编译与运行

#### 环境要求

- Android Studio Hedgehog (2023.1.1) 或更高
- JDK 17
- Android SDK 35（compileSdk）
- 最小支持设备：Android 7.0 (API 24)
- Gradle 8.14（已随项目附带 Wrapper，自动下载）

#### 命令行编译

```shell
cd android
./gradlew assembleDebug
```

生成的 APK 位于 `android/app/build/outputs/apk/debug/app-debug.apk`。

#### Android Studio 打开

1. Android Studio → Open → 选择 `android/` 目录
2. 等待 Gradle 同步完成（首次会下载依赖，约 5-10 分钟）
3. 连接 Android 手机（开启 USB 调试）或启动模拟器
4. 点击 Run ▶

### 第四步：使用你的自定义模型

1. 训练你自己的模型：`python train.py`（产物：`runs/detect/train/weights/best.pt`）
2. 导出为 TFLite：
   ```shell
   python export_tflite.py --model runs/detect/train/weights/best.pt --imgsz 320 --int8
   ```
3. 将 `export/best_tflite.tflite` 与 `export/labels.txt` 复制到 `android/app/src/main/assets/`
4. 如果文件名不是默认的，修改 `MainActivity.kt` 中的 `createDetector()`：
   ```kotlin
   private fun createDetector(backend: String): YoloV11Detector {
       return YoloV11Detector(
           context = this,
           modelPath = "best_tflite.tflite",  // ← 改成你的文件名
           labelsPath = "labels.txt",
           inputSize = 320,
           backend = backend,
       )
   }
   ```

### 性能优化（已实施）

本项目已实施多项优化，从 1.2 FPS 提升到 **15+ FPS**（12 倍提速）：

#### 模型层面

| 优化项 | 操作 | 效果 |
|--------|------|------|
| 输入尺寸 | 从 640×640 降到 320×320 | 推理速度 4 倍提升 |
| INT8 量化 | `--int8` 导出 | 体积减小 4 倍，速度提升 30-50% |

#### 推理后端

支持 4 种推理后端，通过界面按钮循环切换：
1. **auto**（默认）：自动选择（NNAPI > GPU > CPU）
2. **nnapi**：骁龙 NPU 加速（API 28+，红米 K70 Pro 实测最优）
3. **gpu**：Adreno GPU 加速
4. **cpu**：XNNPACK 4 线程（兼容性最好）

#### 代码层面

| 优化项 | 实现 | 效果 |
|--------|------|------|
| 异步推理 | 协程 + Channel 背压 | UI 永不卡顿，推理不阻塞相机 |
| 帧丢弃 | `isInferenceRunning` 原子标志 | 上一帧未完成时直接丢弃新帧 |
| 缓冲区复用 | 预处理数组/bitmap 全部复用 | 零 GC 分配，避免停顿 |
| 批量写入 | `asFloatBuffer().put()` | 比逐个 `putFloat` 快 3-5 倍 |
| 乘法替代除法 | `*0.003922f` 替代 `/255` | 循环内提速 |
| 相机分辨率 | `setTargetResolution(640, 480)` | 减少预处理像素量 |
| RGBA 输出 | `OUTPUT_IMAGE_FORMAT_RGBA_8888` | 避免 YUV→Bitmap 转换 |
| ImageProxy 及时关闭 | 提取数据后立即 `close()` | 避免 `maxImages` 泄漏 |

### 常见问题

**Q: Android Studio 提示 "Minimum supported Gradle version is 8.9"**
A: 项目已升级到 Gradle 8.14。如果仍报错，删除 `android/.gradle/` 目录后重新同步。

**Q: 提示 "Detector init failed"**
A: 检查 `assets/` 目录下是否有 `.tflite` 模型和 `labels.txt` 文件。

**Q: 检测框位置偏移**
A: `OverlayView` 使用 Matrix 自动处理旋转。如仍有问题，检查 `imageInfo.rotationDegrees` 是否正确传入。

**Q: 画面卡顿**
A: (1) 点击"切换后端"按钮尝试 NNAPI；(2) 确认使用的是 320×320 模型；(3) 低端设备考虑 `--int8` 量化模型。

**Q: 想要前置相机镜像**
A: 在 `MainActivity.DetectionAnalyzer.analyze()` 中将 `isMirror` 改为 `true`，或扩展 `CameraManager` 暴露当前方向。

---

## 项目结构

```
yolov11/
├── datasets/              # 数据集（gitignore，需自行放置）
├── images/                # 测试图片
├── res/                   # 文档资源（截图）
├── export/                # TFLite 模型导出产物（含 .tflite 和 labels.txt）
├── android/               # Android 实时识别工程
├── predict.py             # Python 端推理
├── train.py              # Python 端训练
├── test.py               # Python 端验证
├── export_tflite.py       # TFLite 导出脚本（支持 FP32/INT8、自定义尺寸）
├── requirements.txt       # Python 依赖清单
└── README.md              # 本文档
```

## 完整工作流

1. 下载 yolov11 项目
2. 下载国际象棋检测数据集 
3. 运行 `predict.py` 验证推理流程
4. 将数据集解压，替换 `datasets/` 文件夹
5. 运行 `train.py` 进行训练
6. 运行 `export_tflite.py --imgsz 320 --int8` 导出 TFLite 模型
7. 将导出的模型复制到 `android/app/src/main/assets/`
8. 编译并运行 Android App（`cd android && ./gradlew assembleDebug`）
9. 在手机上安装 APK，享受实时视频识别