285 lines
7.5 KiB
Markdown
285 lines
7.5 KiB
Markdown
# Sophon Chakcy 插件管理系统使用文档
|
||
|
||
## 系统概述
|
||
|
||
Sophon Chakcy 是一个基于 Sophon SAIL 的插件化目标检测框架，核心是动态插件管理系统，而非具体的检测算法。YOLOv8 仅作为预置的插件示例，系统支持任意检测算法的插件化扩展。
|
||
|
||
### 核心特性
|
||
|
||
- **动态插件加载**：运行时根据名称动态加载对应检测器
|
||
- **统一配置管理**：集中管理所有插件配置
|
||
- **资源虚拟化**：支持 SQLite VFS 打包模型和配置
|
||
- **模块化设计**：插件间互相独立，易于扩展和维护
|
||
|
||
## 核心架构
|
||
|
||
``text
|
||
sophon_chakcy/
|
||
├── get_detector.py # 核心插件管理器
|
||
├── __init__.py # 工具函数
|
||
└── build.py # 插件打包工具
|
||
```
|
||
|
||
## 关键组件解析
|
||
|
||
### 1. 插件管理器 (get_detector.py)
|
||
|
||
```python
|
||
def get_detector(name: str, is_vfs: bool = False):
|
||
"""核心插件加载函数
|
||
|
||
Args:
|
||
name: 插件名称（在config.json中定义）
|
||
is_vfs: 是否从VFS加载资源
|
||
|
||
Returns:
|
||
tuple: (检测器类, 配置字典)
|
||
"""
|
||
```
|
||
|
||
**工作原理：**
|
||
|
||
1. 根据插件名称查找 `config.json` 中的配置
|
||
2. 动态导入对应的 Python 模块
|
||
3. 加载插件配置文件
|
||
4. 返回检测器类和配置对象
|
||
|
||
### 2. 配置文件结构
|
||
|
||
```json
|
||
{
|
||
"model_map": {
|
||
"yolov8": {
|
||
"name": "yolov8",
|
||
"module": "YOLOv8.yolov8_detector", # 模块导入路径
|
||
"config": "configs/yolov8_config.json" # 插件配置文件
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## 插件接口开发指南
|
||
|
||
### 插件接口规范
|
||
|
||
每个插件必须提供以下接口：
|
||
|
||
#### 1. 配置类（必需）
|
||
|
||
```python
|
||
from dataclasses import dataclass
|
||
from typing import Dict, Any
|
||
|
||
@dataclass
|
||
class PluginConfig:
|
||
"""插件配置基类"""
|
||
bmodel_path: str
|
||
classes: list
|
||
|
||
@classmethod
|
||
def from_dict(cls, data: Dict[str, Any]) -> "PluginConfig":
|
||
"""从字典创建配置对象"""
|
||
return cls(**data)
|
||
```
|
||
|
||
#### 2. 检测器类（必需）
|
||
|
||
```python
|
||
class Detector:
|
||
"""插件检测器基类"""
|
||
|
||
def __init__(self, config_dict: Dict[str, Any], is_vfs: bool = False,
|
||
vfs_path: str = "./application.svfs", dev_id: int = 0,
|
||
conf_thresh: float = 0.25, nms_thresh: float = 0.7):
|
||
"""
|
||
初始化检测器
|
||
|
||
Args:
|
||
config_dict: 配置字典
|
||
is_vfs: 是否使用VFS
|
||
vfs_path: VFS文件路径
|
||
dev_id: 设备ID
|
||
conf_thresh: 置信度阈值
|
||
nms_thresh: NMS阈值
|
||
"""
|
||
self.config = PluginConfig.from_dict(config_dict)
|
||
# 其他初始化逻辑...
|
||
|
||
def detect_single_image(self, image_path: str, output_dir: str = "./results") -> list:
|
||
"""单张图像检测接口"""
|
||
pass
|
||
|
||
def detect_images_in_directory(self, input_dir: str, output_dir: str = "./results"):
|
||
"""批量图像检测接口"""
|
||
pass
|
||
```
|
||
|
||
### 创建新插件的完整流程
|
||
|
||
#### 步骤1：创建插件目录结构
|
||
|
||
```text
|
||
my_detector/
|
||
├── __init__.py
|
||
├── my_detector.py # 主检测器文件
|
||
├── preprocess.py # 预处理模块（可选）
|
||
├── postprocess.py # 后处理模块（可选）
|
||
└── utils.py # 工具函数（可选）
|
||
```
|
||
|
||
#### 步骤2：实现检测器类
|
||
|
||
```python
|
||
# my_detector/my_detector.py
|
||
import os
|
||
import numpy as np
|
||
from dataclasses import dataclass
|
||
from typing import List, Dict, Any
|
||
|
||
import sophon_chakcy.sail as sail
|
||
from .preprocess import Preprocessor
|
||
from .postprocess import Postprocessor
|
||
|
||
@dataclass
|
||
class MyDetectorConfig:
|
||
"""自定义检测器配置"""
|
||
bmodel_path: str
|
||
classes: List[str]
|
||
input_size: tuple = (640, 640)
|
||
mean: List[float] = None
|
||
std: List[float] = None
|
||
|
||
@classmethod
|
||
def from_dict(cls, data: Dict[str, Any]) -> "MyDetectorConfig":
|
||
return cls(**data)
|
||
|
||
class Detector:
|
||
"""自定义检测器实现"""
|
||
|
||
def __init__(self, config_dict: Dict[str, Any], is_vfs: bool = False,
|
||
vfs_path: str = "./application.svfs", dev_id: int = 0,
|
||
conf_thresh: float = 0.25, nms_thresh: float = 0.7):
|
||
|
||
# 解析配置
|
||
self.config = MyDetectorConfig.from_dict(config_dict)
|
||
|
||
# 加载模型
|
||
if is_vfs:
|
||
from sqlite_vfs.core import SQLiteVFS
|
||
vfs = SQLiteVFS(vfs_path)
|
||
bmodel_bytes = vfs.read_file(self.config.bmodel_path)
|
||
bmodel_size = vfs.get_file_info(self.config.bmodel_path)["file_size"]
|
||
self.net = sail.Engine(bmodel_bytes, bmodel_size, dev_id, sail.IOMode.SYSO)
|
||
else:
|
||
self.net = sail.Engine(self.config.bmodel_path, dev_id, sail.IOMode.SYSO)
|
||
|
||
# 初始化组件
|
||
self.preprocessor = Preprocessor(self.config)
|
||
self.postprocessor = Postprocessor(
|
||
conf_thresh=conf_thresh,
|
||
nms_thresh=nms_thresh,
|
||
classes=self.config.classes
|
||
)
|
||
|
||
# 其他初始化...
|
||
print(f"插件 '{self.__class__.__name__}' 初始化完成")
|
||
|
||
def detect_single_image(self, image_path: str, output_dir: str = "./results"):
|
||
"""实现单图检测逻辑"""
|
||
# 1. 读取图像
|
||
# 2. 预处理
|
||
# 3. 推理
|
||
# 4. 后处理
|
||
# 5. 返回结果
|
||
pass
|
||
|
||
def detect_images_in_directory(self, input_dir: str, output_dir: str = "./results"):
|
||
"""实现批量检测逻辑"""
|
||
for img_file in os.listdir(input_dir):
|
||
img_path = os.path.join(input_dir, img_file)
|
||
self.detect_single_image(img_path, output_dir)
|
||
```
|
||
|
||
#### 步骤3：创建插件配置文件
|
||
```json
|
||
// configs/my_detector_config.json
|
||
{
|
||
"bmodel_path": "models/my_model.bmodel",
|
||
"classes": ["cat", "dog", "person"],
|
||
"input_size": [640, 640],
|
||
"mean": [0.485, 0.456, 0.406],
|
||
"std": [0.229, 0.224, 0.225]
|
||
}
|
||
```
|
||
|
||
#### 步骤4：注册插件
|
||
|
||
修改 `config.json` 添加新插件：
|
||
|
||
```json
|
||
{
|
||
"model_map": {
|
||
"yolov8": {
|
||
"module": "YOLOv8.yolov8_detector",
|
||
"config": "configs/yolov8_config.json"
|
||
},
|
||
"my_detector": {
|
||
"module": "my_detector.my_detector",
|
||
"config": "configs/my_detector_config.json"
|
||
},
|
||
"faster_rcnn": {
|
||
"module": "faster_rcnn.detector",
|
||
"config": "configs/faster_rcnn_config.json"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 步骤5：测试插件
|
||
|
||
```bash
|
||
# 使用新插件
|
||
python main.py --name my_detector --input ./test.jpg
|
||
```
|
||
|
||
### 插件打包与部署
|
||
|
||
#### 1. 打包工具详解 (build.py)
|
||
|
||
构建工具执行以下任务：
|
||
|
||
1. **读取配置**：解析 `config.json` 中的所有插件配置
|
||
2. **打包模块**：将插件模块打包到 SQLite 模块库
|
||
3. **打包资源**：将模型和配置文件打包到 VFS
|
||
4. **生成部署包**：创建完整的可部署包
|
||
|
||
#### 2. 打包命令
|
||
|
||
```bash
|
||
# 基本打包
|
||
python -m sophon_chakcy.build
|
||
|
||
# 自定义输出路径
|
||
python -m sophon_chakcy.build --vfs_path my_app.svfs --mbank_path my_plugins.mbank
|
||
|
||
# 详细日志
|
||
python -m sophon_chakcy.build --verbose
|
||
```
|
||
|
||
#### 3. 部署结构
|
||
|
||
```text
|
||
部署目录/
|
||
├── main.py # 主程序（使用VFS和模块库）
|
||
├── application.svfs # 虚拟文件系统
|
||
│ ├── config.json
|
||
│ ├── configs/yolov8_config.json
|
||
│ ├── configs/my_detector_config.json
|
||
│ ├── models/yolov8n.bmodel
|
||
│ └── models/my_model.bmodel
|
||
└── plugins.mbank # Python模块库
|
||
├── YOLOv8
|
||
├── my_detector
|
||
└── faster_rcnn
|
||
```
|