# StrawberryScan

**Repository Path**: junhuisirup/strawberry-scan

## Basic Information

- **Project Name**: StrawberryScan
- **Description**: 硕果鉴代码仓库
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-14
- **Last Updated**: 2026-06-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# StrawberryScan（硕果鉴）

<div align="center">

**基于 AIPC 与多模态大模型的端侧 AI 草莓品控工具**

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![Qt6](https://img.shields.io/badge/Qt-6.0+-green.svg)](https://www.qt.io/)

[English](README.en.md) | 简体中文

</div>

---

## 🧪 测试

### 测试结构

项目包含完整的测试套件，分为以下类型：

```
tests/
├── unit/              # 单元测试
│   ├── test_adapter.py                # 聊天适配器测试
│   ├── test_convert_to_yolo.py       # YOLO格式转换测试
│   ├── test_rag_core.py              # RAG核心组件测试
│   ├── test_strawberry_loader.py     # 草莓知识库加载器测试
│   ├── test_yolo_core.py             # YOLO核心功能测试
│   └── test_markdown_renderer.py     # Markdown渲染器测试
├── integration/       # 集成测试
│   ├── test_rag_integration.py        # RAG系统组件集成测试
│   └── test_rag_yolo_integration.py   # YOLO+RAG端到端集成测试
└── performance/       # 性能测试
    └── xPUMonitor.py                 # 系统性能监控
```

### 运行测试

#### 运行所有集成测试

```bash
# RAG 系统组件测试
python tests/integration/test_rag_integration.py

# YOLO + RAG 端到端测试
python tests/integration/test_rag_yolo_integration.py
```

#### 运行单元测试

```bash
# 聊天适配器测试
python tests/unit/test_adapter.py

# YOLO 格式转换测试
python tests/unit/test_convert_to_yolo.py

# RAG 核心组件测试
python tests/unit/test_rag_core.py

# 草莓知识库加载器测试
python tests/unit/test_strawberry_loader.py

# YOLO 核心功能测试
python tests/unit/test_yolo_core.py

# Markdown 渲染器测试
python tests/unit/test_markdown_renderer.py
```

#### 运行所有测试（使用 pytest）

```bash
# 安装 pytest
pip install pytest pytest-cov

# 运行所有测试
pytest tests/

# 生成覆盖率报告
pytest tests/ --cov=src --cov-report=html
```

### 测试覆盖范围

| 测试类型 | 测试文件 | 覆盖组件 |
|---------|---------|---------|
| 集成测试 | test_rag_integration.py | 嵌入模型、向量存储、检索器、RAG链 |
| 集成测试 | test_rag_yolo_integration.py | YOLO检测、YOLO分割、GenieChatRAG、完整流程 |
| 单元测试 | test_adapter.py | 聊天适配器 |
| 单元测试 | test_convert_to_yolo.py | YOLO格式转换 |
| 单元测试 | test_rag_core.py | RAG核心组件 |
| 单元测试 | test_strawberry_loader.py | 草莓知识库加载器 |
| 单元测试 | test_yolo_core.py | YOLO核心功能 |
| 单元测试 | test_markdown_renderer.py | Markdown渲染器 |

### 测试最佳实践

1. **集成测试**：验证多个组件协同工作
2. **单元测试**：验证单个组件的功能
3. **性能测试**：监控系统性能指标
4. **端到端测试**：验证完整的用户流程

更多测试详情请参考 [tests/README.md](tests/README.md)

---

## 📖 项目简介

**StrawberryScan（硕果鉴）** 是一款面向精品草莓种植户的智能品控工具，结合 **YOLO11** 目标检测与 **多模态大模型**，实现在端侧设备（如搭载骁龙 X Elite 的 AIPC）上对草莓成熟度、病虫害等进行精准识别与分析，提升优果率 20% 以上，助力现代农业智能化升级。

我们不仅是工具，更是 **"数字品味师" + "风土认证官"**，将科技与文化品味深度融合，为草莓赋予数字身份与文化内涵。

### ✨ 核心特性

- 🍓 **成熟度识别**：准确率 >95%，辅助采摘决策
- 🐛 **病虫害预警**：准确率 >90%，提前发现病害风险
- 📄 **AI 品鉴报告**：可视化 + 文化感，提供数字品质证明
- 🌱 **多场景适配**：支持田间实时识别与 PC 端深度分析
- ⚡ **端侧部署**：运行于 AIPC，支持 NPU 加速，零延迟、高隐私
- 🤖 **智能对话**：内置草莓种植专家系统，提供专业建议
- 📚 **RAG 增强检索**：基于知识库的智能问答，提供专业种植指导
- 🔍 **多策略检索**：支持相似度、MMR、混合检索等多种策略

---

## 🏗️ 技术架构

![技术架构图](misc/技术架构图.png)

### 核心流程

1. **YOLO11 检测**：负责草莓目标的快速定位与检测
2. **YOLO11 分割**：识别草莓病虫害区域
3. **RAG 知识检索**：基于检测结果从知识库检索相关知识
4. **多模态大模型**：结合检测结果和检索知识，进行视觉-语言联合推理，生成分析报告
5. **端侧部署**：运行于 AIPC，支持 NPU 加速，零延迟、高隐私

### 技术栈

| 类别 | 技术选型 |
|------|----------|
| 前端界面 | Qt6 (PySide6) + QML |
| AI 模型 | YOLO11 + Qwen2.5 |
| 深度学习框架 | PyTorch + Ultralytics |
| RAG 系统 | BGE 嵌入模型 + ChromaDB |
| 向量数据库 | ChromaDB |
| 嵌入模型 | BGE (Beijing Academy of Artificial Intelligence) |
| 部署环境 | 骁龙 X Elite AIPC，支持 NPU 推理加速 |
| 图像处理 | OpenCV + PIL |
| 通信协议 | HTTP + WebSocket |

---

## 📁 项目结构

```
strawberry-scan/
├── src/                    # 源代码目录
│   ├── app/              # 应用层
│   │   ├── main.py        # 应用程序主入口
│   │   ├── StrawBerryScanBackend.py    # 后端服务
│   │   ├── ChatAdapter.py           # 聊天适配器
│   │   ├── reportAdapter.py         # 报告适配器
│   │   ├── common/      # 公共模块
│   │   │   ├── strawberry_info.py       # 草莓信息管理
│   │   │   ├── rag_prompt_builder.py    # RAG提示构建器
│   │   │   ├── NumpyImageProvider.py    # 图像提供器
│   │   │   ├── beautiful_annotator.py   # 图像标注美化
│   │   │   ├── report_generator.py      # 报告生成器
│   │   │   ├── markdown_renderer.py     # Markdown渲染
│   │   │   ├── analysis_history.py      # 分析历史
│   │   │   └── token_utils.py           # Token工具
│   │   ├── chat/        # 聊天模块
│   │   │   ├── GenieChatAPI.py          # 多模态大模型API
│   │   │   ├── GenieChatRAG.py          # RAG增强的GenieChat API
│   │   │   └── rag/                     # RAG子模块
│   │   │       ├── rag_chain.py         # RAG链实现
│   │   │       ├── retriever.py         # 检索器
│   │   │       └── strawberry_rag.py    # 草莓RAG系统
│   │   ├── analyzer/    # 分析模块
│   │   │   └── strawberry_analyzer.py   # 草莓分析器
│   │   └── video/       # 视频处理模块
│   │       ├── video_stream_processor.py  # 视频流处理器
│   │       ├── video_analysis_data.py     # 视频分析数据
│   │       └── thread_safety.py           # 线程安全
│   ├── inference/        # 推理模块
│   │   ├── yoloPipline/  # YOLO推理管线
│   │   │   ├── yolov11_pipeline.py     # 统一Pipeline
│   │   │   ├── intermediate_processing.py  # 中间处理
│   │   │   ├── detection/   # 目标检测模块
│   │   │   │   └── yolov11_det.py
│   │   │   ├── segmentation/  # 语义分割模块
│   │   │   │   └── yolov11_seg.py
│   │   │   └── tracking/    # 目标跟踪模块
│   │   │       ├── ocsort_tracker.py
│   │   │       ├── track_info.py
│   │   │       ├── trackerInstances.py
│   │   │       ├── mobilenetv2.py
│   │   │       └── ocsort_module/
│   │   │           └── ocsort_wrapper.py
│   │   ├── rag/          # RAG推理模块
│   │   │   └── embedding.py          # BGE嵌入模型
│   │   └── mllm/         # 多模态大模型模块
│   ├── GenieServiceRAG/  # RAG服务模块
│   │   ├── chat.py       # 聊天服务
│   │   ├── Docutils.py   # 文档工具
│   │   └── ragEmb/       # RAG嵌入模块
│   │       ├── vector_store.py       # ChromaDB向量存储
│   │       └── processors/           # 数据处理器
│   │           ├── json_loader.py    # JSON知识库加载器
│   │           └── strawberry_loader.py  # 草莓知识库加载器
│   ├── frontend/         # QML界面文件
│   │   ├── Main.qml      # 主界面
│   │   ├── ChatPanel.qml # 聊天面板
│   │   ├── ImageDisplayArea.qml
│   │   └── ...
│   ├── models/           # 模型文件
│   │   └── yolo/         # YOLO模型
│   │       └── yolo_bundle/
│   ├── config/           # 配置文件
│   │   └── paths.py      # 路径配置
│   └── utils/            # 工具模块
│       └── convert_to_yolo_format.py
├── data/                 # 数据目录
│   ├── datasets/         # 训练数据集
│   │   ├── detect/       # 检测数据集
│   │   └── yolo_labels/  # YOLO标注
│   ├── annotations/      # 标注文件
│   ├── images/           # 图像文件
│   ├── rag/              # RAG知识库
│   │   └── knowledge/    # 知识库文件
│   └── results/          # 结果输出
├── tests/                # 测试文件
│   ├── unit/             # 单元测试
│   │   ├── test_adapter.py
│   │   ├── test_convert_to_yolo.py
│   │   ├── test_rag_core.py
│   │   ├── test_strawberry_loader.py
│   │   ├── test_yolo_core.py
│   │   └── test_markdown_renderer.py
│   ├── integration/      # 集成测试
│   │   ├── test_rag_integration.py
│   │   └── test_rag_yolo_integration.py
│   └── performance/      # 性能测试
│       └── xPUMonitor.py
├── scripts/              # 工具脚本
│   ├── compile_qrc.py    # QRC编译脚本
│   ├── check_env.py      # 环境检查脚本
│   └── install_ocsort.py # OCSort安装脚本
├── external/             # 外部依赖
│   └── ocsort/           # OCSort跟踪算法
├── misc/                 # 杂项资源
│   ├── 草莓底图模板.png
│   ├── 技术架构图.png
│   └── ...
├── ultralytics/          # Ultralytics配置
├── train.py              # 模型训练脚本
├── setup.py              # 安装脚本
├── pyproject.toml        # 项目配置文件
├── requirements.txt      # 依赖列表
├── README.md             # 项目说明（中文）
├── README.en.md          # 项目说明（英文）
├── RAG_README.md         # RAG系统说明
└── LICENSE               # MIT许可证
```

---

## 🚀 快速开始

### 环境要求

- **Python**: 3.8 或更高版本
- **操作系统**: Windows/Linux/macOS
- **硬件**: 支持 NPU 的 AIPC（如骁龙 X Elite）或普通 GPU
- **内存**: 建议 8GB 以上
- **存储**: 至少 5GB 可用空间

### 安装方法

#### 方法一：使用 pip 安装（推荐）

```bash
# 克隆项目
git clone https://github.com/your-repo/StrawberryScan.git
cd StrawberryScan

# 安装依赖
pip install -e .
```

#### 方法二：手动安装依赖

```bash
# 克隆项目
git clone https://github.com/your-repo/StrawberryScan.git
cd StrawberryScan

# 创建虚拟环境（推荐）
python -m venv venv
source venv/bin/activate  # Linux/macOS
# 或
venv\Scripts\activate  # Windows

# 安装依赖
pip install -r requirements.txt
```

### 运行程序

```bash
# 启动应用程序
python -m strawberry_scan

# 或直接运行主程序
python src/app/main.py
```

### 使用说明

1. **启动应用**：运行主程序后，会打开图形界面
2. **上传图片**：点击"上传图片"按钮，选择草莓图片
3. **开始分析**：点击"开始分析"按钮，系统会自动进行检测和分割
4. **查看结果**：分析完成后，会显示检测结果和AI分析报告
5. **智能对话**：可以在聊天面板中与草莓专家系统进行对话

---

## 🧪 模型训练

### 准备数据集

将训练数据放置在 `data/datasets/` 目录下，按照 YOLO 格式组织。

### 训练模型

```bash
# 训练检测模型
python train.py
```

训练配置可以在 `train.py` 中修改，包括：
- 模型架构（yolo11.yaml 等）
- 训练轮数（epochs）
- 批次大小（batch）
- 优化器类型（optimizer）

---

## 📚 RAG 智能检索系统

### 系统概述

StrawberryScan 集成了先进的 RAG（检索增强生成）系统，通过结合专业草莓种植知识库，为用户提供更准确、更专业的分析和建议。

### 核心组件

#### 1. 嵌入模型 (BGE)
- **模型**: BGE (Beijing Academy of Artificial Intelligence General Embedding)
- **功能**: 将文本转换为高维向量表示
- **支持**: 单文本嵌入、批量文本嵌入
- **QAI 集成**: 支持 Qualcomm QAI AppBuilder 框架

#### 2. 向量数据库 (ChromaDB)
- **功能**: 存储和检索嵌入向量
- **特性**: 高效相似度搜索、元数据过滤
- **持久化**: 支持本地存储，无需外部数据库

#### 3. 多策略检索器
支持多种检索策略，满足不同场景需求：

| 策略 | 说明 | 适用场景 |
|------|------|----------|
| **相似度检索** | 基于余弦相似度的最相似文档检索 | 快速问答、简单查询 |
| **MMR 检索** | 最大边际相关性，平衡相关性和多样性 | 需要多角度信息的查询 |
| **混合检索** | 结合相似度和多样性 | 综合性分析 |
| **分层检索** | 按类别分层检索 | 需要特定领域知识的查询 |

#### 4. RAG 链
- **功能**: 将检索到的知识整合到大模型推理中
- **支持**: 带引用的查询、对话记忆、流式输出
- **集成**: 与 GenieChat API 无缝集成

### 知识库管理

#### 知识库格式
知识库支持 JSON 格式，结构如下：

```json
{
  "title": "草莓灰霉病防治",
  "content": "灰霉病是草莓常见病害...",
  "category": "病害防治",
  "tags": ["灰霉病", "防治", "真菌"]
}
```

#### 知识库位置
- 默认路径: `data/rag/knowledge/`
- 支持多个 JSON 文件
- 自动加载和索引

### 使用示例

#### 1. 普通问答（RAG 增强）

```python
from src.app.chat.GenieChatRAG import GenieChatRAG

# 初始化 RAG 系统
rag = GenieChatRAG(model_name="IBM-Granite-v3.1-8B", auto_build=True)

# 提问
for response in rag.chat("如何防治草莓灰霉病？"):
    print(response, end='')
```

#### 2. 基于检测结果的分析

```python
# 模拟检测结果
detection_data = {
    "strawberries": [
        {"id": 1, "confidence": 0.95, "bbox": [100, 100, 200, 200]},
        {"id": 2, "confidence": 0.88, "bbox": [300, 150, 400, 250]}
    ],
    "diseases": [
        {"type": "灰霉病", "confidence": 0.92, "area": [150, 120, 180, 140]}
    ]
}

# RAG 增强的分析
for response in rag.analyze_strawberries(detection_data):
    print(response, end='')
```

### RAG 配置

可以在 `src/app/common/strawberry_rag.py` 中配置 RAG 系统：

```python
# 检索策略
RETRIEVAL_STRATEGY = "similarity"  # similarity, mmr, hybrid, layered

# 检索参数
TOP_K = 5  # 返回的文档数量
SCORE_THRESHOLD = 0.7  # 相似度阈值

# 嵌入模型
EMBEDDING_MODEL = "BAAI/bge-m3"
EMBEDDING_DEVICE = "cuda"  # cuda, cpu
```

---

## 📊 支持的病虫害类型

| 类别ID | 名称 | 颜色 |
|--------|------|------|
| 0 | 角斑病 (Angular Leafspot) | 红色 |
| 1 | 白粉病叶 (Powdery Mildew Leaf) | 黄色 |
| 2 | 炭疽病果腐 (Anthracnose Fruit Rot) | 蓝色 |
| 3 | 花腐病 (Blossom Blight) | 紫色 |
| 4 | 灰霉病 (Gray Mold) | 深紫 |
| 5 | 叶斑病 (Leaf Spot) | 绿色 |

---

## 🔧 配置说明

### 路径配置

所有路径配置都在 `src/config/paths.py` 中统一管理，包括：
- 项目根目录
- 数据目录
- 模型目录
- 资源目录

### 模型配置

模型文件位于 `src/models/yolo/yolo_bundle/` 目录下，包括：
- `quantized_qnn/` - 量化后的 QNN 模型（用于 NPU 加速）
- `optimized_onnx/` - 优化后的 ONNX 模型

---

## 🤝 贡献指南

欢迎贡献代码！请遵循以下步骤：

1. Fork 本项目
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

---

## 📝 许可证

本项目采用 MIT 许可证 - 详见 [LICENSE](LICENSE) 文件

---

## 👨‍💻 作者

**JunhuiSirup**

---

## 🙏 致谢

- [Ultralytics](https://github.com/ultralytics/ultralytics) - YOLO11 框架
- [PySide6](https://www.qt.io/) - Qt6 Python 绑定
- [Qualcomm](https://www.qualcomm.com/) - QNN 工具链和 NPU 支持
- [BAAI](https://github.com/FlagOpen/FlagEmbedding) - BGE 嵌入模型
- [Chroma](https://www.trychroma.com/) - ChromaDB 向量数据库
- [LangChain](https://github.com/langchain-ai/langchain) - RAG 链实现灵感

---

## 📮 联系方式

如有问题或建议，请通过以下方式联系：
- 提交 [Issue](https://github.com/your-repo/StrawberryScan/issues)
- 发送邮件至：lijunhui9408@163.com

---

<div align="center">

**如果这个项目对您有帮助，请给个 ⭐️ Star 支持一下！**

Made with ❤️ by StrawberryScan Team

</div>