# pyolo

**Repository Path**: techwolf/pyolo

## Basic Information

- **Project Name**: pyolo
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-13
- **Last Updated**: 2025-09-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# YOLO推理服务

基于FastAPI和Ultralytics YOLO实现的高性能目标检测服务，支持YOLO 11 n和s模型的自动下载和推理。

## 功能特性

- 🚀 **高性能推理**: 基于Ultralytics YOLO，支持GPU加速
- 📦 **自动模型下载**: 启动时自动下载YOLO 11 n和s模型
- 🌐 **RESTful API**: 基于FastAPI的现代Web API
- 📸 **多种输入方式**: 支持Base64编码和文件上传
- 🎯 **灵活配置**: 可调节置信度阈值、IoU阈值等参数
- 🔍 **类别过滤**: 支持指定检测特定类别的物体
- 🖼️ **结果可视化**: 可返回绘制检测结果的图像
- 📊 **批量处理**: 支持批量图像检测
- 🐳 **容器化部署**: 提供Docker和Docker Compose配置

## 支持的模型

| 模型名称 | 大小 | 描述 |
|---------|------|------|
| yolo11n | Nano | 最小模型，速度最快 |
| yolo11s | Small | 小型模型，平衡速度和精度 |

## 快速开始

### 方式1: 直接运行

1. **安装依赖**
```bash
pip install -r requirements.txt
```

2. **启动服务**
```bash
python yolo_inference_server.py
```

或使用启动脚本：
```bash
./start_server.sh
```

### 方式2: 使用Docker

1. **构建镜像**
```bash
docker build -t yolo-inference .
```

2. **运行容器**
```bash
docker run -p 8000:8000 -v $(pwd)/models:/app/models yolo-inference
```

### 方式3: 使用Docker Compose

```bash
docker-compose up -d
```

## API文档

服务启动后，访问以下地址查看API文档：
- Swagger UI: http://localhost:8000/docs
- ReDoc: http://localhost:8000/redoc

### 主要接口

#### 1. 健康检查
```http
GET /health
```

#### 2. 模型管理
```http
GET /models                           # 列出所有模型
GET /models/{model_name}              # 获取模型信息
POST /models/{model_name}/download    # 下载模型
POST /models/{model_name}/load        # 加载模型
DELETE /models/{model_name}           # 卸载模型
```

#### 3. 目标检测
```http
POST /detect                          # Base64图像检测
POST /detect/file                     # 文件上传检测
POST /batch_detect                    # 批量检测
```

#### 4. 其他接口
```http
GET /classes                          # 获取支持的类别
```

## Web演示界面

服务启动后，可以通过浏览器打开 `web_demo.html` 文件使用图形界面进行检测：

### 主要功能
- 🔧 **服务器配置**: 可以设置自定义的服务器地址
- 🔗 **连接测试**: 测试与YOLO推理服务的连接状态
- 📤 **文件上传**: 支持拖拽或点击上传图像文件
- ⚙️ **参数调节**: 可调节置信度阈值、IoU阈值等参数
- 🔧 **高级设置**: 类别过滤、返回裁剪图像等选项
- 📊 **性能监控**: 查看实时性能统计和推理速率
- 📱 **响应式设计**: 支持手机和平板设备

### 使用步骤
1. 在浏览器中打开 `web_demo.html`
2. 设置服务器地址（默认: http://localhost:8000）
3. 点击"测试连接"确认服务可用
4. 选择图像文件进行上传
5. 调整检测参数（可选）
6. 点击"开始检测"查看结果

## 使用示例

### Python客户端示例

```python
import requests
import base64

# 文件上传检测
with open('image.jpg', 'rb') as f:
    files = {'file': f}
    data = {
        'model_name': 'yolo11n',
        'confidence_threshold': 0.5,
        'draw_results': True
    }
    response = requests.post('http://localhost:8000/detect/file', 
                           files=files, data=data)
    result = response.json()
    print(result)
```

### Base64检测示例

```python
import requests
import base64

# 读取图像并编码为Base64
with open('image.jpg', 'rb') as f:
    image_data = base64.b64encode(f.read()).decode('utf-8')

# 发送检测请求
data = {
    "model_name": "yolo11n",
    "image_data": image_data,
    "confidence_threshold": 0.5,
    "iou_threshold": 0.4,
    "draw_results": True
}

response = requests.post('http://localhost:8000/detect', json=data)
result = response.json()
print(result)
```

### cURL示例

```bash
# 文件上传检测
curl -X POST "http://localhost:8000/detect/file" \
     -F "file=@image.jpg" \
     -F "model_name=yolo11n" \
     -F "confidence_threshold=0.5" \
     -F "draw_results=true"

# 获取模型列表
curl -X GET "http://localhost:8000/models"

# 健康检查
curl -X GET "http://localhost:8000/health"
```

## 配置说明

### 环境变量

| 变量名 | 默认值 | 描述 |
|--------|--------|------|
| HOST | 0.0.0.0 | 服务器主机地址 |
| PORT | 8000 | 服务器端口 |
| WORKERS | 1 | 工作进程数 |
| MODELS_DIR | ./models | 模型文件目录 |

### 配置文件

编辑 `config.yaml` 文件可以修改详细配置：

```yaml
server:
  host: "0.0.0.0"
  port: 8000
  workers: 1

models:
  models_dir: "./models"
  default_model: "yolo11n"
  auto_download: true

inference:
  default_confidence_threshold: 0.5
  default_iou_threshold: 0.4
  max_image_size: 4096
```

## 测试

运行测试客户端：

```bash
python test_client.py
```

## 性能优化

1. **GPU加速**: 确保安装了CUDA和对应的PyTorch版本
2. **批量处理**: 使用批量检测接口处理多张图像
3. **模型选择**: 根据需求选择合适的模型大小
4. **参数调优**: 调整置信度阈值和IoU阈值

## 故障排除

### 常见问题

1. **模型下载失败**
   - 检查网络连接
   - 手动下载模型文件到models目录

2. **GPU不可用**
   - 检查CUDA安装
   - 确认PyTorch GPU版本

3. **内存不足**
   - 减少批量大小
   - 使用更小的模型

### 日志查看

```bash
# 查看服务日志
docker-compose logs -f yolo-inference

# 查看实时日志
tail -f /var/log/yolo-inference.log
```

## 开发

### 开发环境设置

```bash
# 克隆代码
git clone <repository>
cd yolo

# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Linux/Mac
# venv\Scripts\activate   # Windows

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

# 开发模式启动
python yolo_inference_server.py --reload
```

### 代码结构

```
yolo/
├── yolo_inference_server.py    # 主服务文件
├── requirements.txt            # Python依赖
├── config.yaml                # 配置文件
├── start_server.sh            # 启动脚本
├── Dockerfile                 # Docker配置
├── docker-compose.yml         # Docker Compose配置
├── test_client.py             # 测试客户端
├── README.md                  # 文档
└── models/                    # 模型文件目录
```

## 许可证

MIT License

## 贡献

欢迎提交Issue和Pull Request！