1. 项目概述

本项目后端是一个基于 FastAPI 构建的高性能异步 API 服务，专为目标检测系统提供完整的后端支持。

4. API 接口规范

4.1 统一响应格式

所有接口遵循统一的 JSON 响应格式：

{
  "code": 200,
  "message": "成功",
  "data": {}
}

4.2 错误响应格式

{
  "detail": "错误信息描述"
}

常见 HTTP 状态码：

  • 200: 成功

  • 400: 请求参数错误

  • 404: 资源不存在

  • 500: 服务器内部错误

  • 504: 请求超时

4.3 文件大小限制

  • 图片文件: 最大 10MB

  • 视频文件: 最大 500MB

  • 模型文件: 最大 500MB

5. 数据库设计

5.1 模型信息存储 (models_info.json)

[
  {
    "filename": "20240321_123456_yolo.pt",
    "name": "YOLO检测模型",
    "dataset": "COCO",
    "base_model": "YOLO",
    "upload_time": "2024-03-21 12:34:56",
    "description": "基于COCO数据集训练的YOLO目标检测模型",
    "version": "1.0",
    "accuracy": 85.5
  }
]

6. 日志系统

6.1 日志配置

def setup_logging():
    """配置日志系统"""
    log_filename = datetime.now().strftime("%Y.%m.%d.log")
    log_filepath = LOGS_DIR / log_filename
    
    formatter = logging.Formatter(
        '%(asctime)s - %(name)s - %(levelname)s - %(message)s',
        datefmt='%Y-%m-%d %H:%M:%S'
    )
    
    # 文件处理器
    file_handler = logging.FileHandler(log_filepath, encoding='utf-8')
    file_handler.setFormatter(formatter)
    file_handler.setLevel(logging.INFO)
    
    # 控制台处理器
    console_handler = logging.StreamHandler()
    console_handler.setFormatter(formatter)
    console_handler.setLevel(logging.INFO)
    
    # 配置根日志记录器
    root_logger = logging.getLogger()
    root_logger.setLevel(logging.INFO)
    root_logger.addHandler(file_handler)
    root_logger.addHandler(console_handler)

6.2 日志级别

  • INFO: 正常操作日志

  • WARNING: 警告信息

  • ERROR: 错误信息

  • CRITICAL: 严重错误

7. 性能优化策略

7.1 异步处理

所有 I/O 密集型操作使用 async/await：

@router.post("/upload/{filename}")
async def upload_image_with_filename(filename: str, file: UploadFile = File(...)):
    content = await file.read()  # 异步读取
    # ...

7.2 流式响应

大文件下载使用流式响应：

return StreamingResponse(
    buffer,
    media_type='application/zip',
    headers={'Content-Disposition': f'attachment; filename="{zip_filename}"'}
)

7.3 模型缓存

YOLO 模型采用全局单例模式，避免重复加载：

current_model = None
​
def get_current_model():
    global current_model
    if current_model is None:
        current_model = YOLO("yolo11n.pt")
    return current_model

8. 安全性考虑

8.1 文件验证

# 验证文件格式
ext = Path(file.filename).suffix.lower()
if ext not in ALLOWED_IMAGE_EXTENSIONS:
    raise HTTPException(status_code=400, detail=f"不支持的图片格式: {ext}")
​
# 验证文件大小
if len(content) > MAX_IMAGE_SIZE:
    raise HTTPException(status_code=400, detail=f"图片文件大小超过限制")

8.2 路径安全

# 使用 Path 对象防止路径遍历攻击
filepath = IMAGES_UPLOAD_DIR / filename
if not filepath.exists():
    raise HTTPException(status_code=404, detail="图片不存在")

8.3 CORS 限制

生产环境应限制 CORS 来源：

app.add_middleware(
    CORSMiddleware,
    allow_origins=["https://yourdomain.com"],  # 限制来源
    allow_credentials=True,
    allow_methods=["GET", "POST", "DELETE"],
    allow_headers=["*"],
)

9. 部署指南

9.1 开发环境启动

# 安装依赖
cd backend
pip install -r requirements.txt
​
# 启动服务（开发模式，自动重载）
python -m uvicorn app:app --host 0.0.0.0 --port 10077 --reload
​
# 或直接运行
python app.py

9.2 生产环境部署

# 使用 Gunicorn + Uvicorn Workers
gunicorn app:app \
  --workers 4 \
  --worker-class uvicorn.workers.UvicornWorker \
  --bind 0.0.0.0:10077 \
  --timeout 300

9.3 Docker 部署

FROM python:3.10-slim
​
WORKDIR /app
​
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
​
COPY . .
​
EXPOSE 10077
​
CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "10077"]

10. 环境变量配置

10.1 必需环境变量

# 大语言模型 API 配置
LLM_API_KEY=your_api_key_here
LLM_BASE_URL=https://api.siliconflow.cn/v1

10.2 可选环境变量

# 服务端口
PORT=10077
​
# 日志级别
LOG_LEVEL=INFO
​
# 模型路径
MODEL_PATH=./models/yolo11n.pt

11. 常见问题（FAQ）

Q1: 如何切换 GPU/CPU 模式？

修改 images.py 中的模型加载代码：

# CPU 模式
current_model.to('cpu')
​
# GPU 模式
current_model.to('cuda')

Q2: 如何添加新的 API 接口？

  1. 在对应模块文件中添加路由函数

  2. 使用 @router.get/post/put/delete 装饰器

  3. 确保在 app.py 中已注册该路由器

Q3: 如何自定义日志格式？

修改 app.py 中的 setup_logging 函数：

formatter = logging.Formatter(
    '%(asctime)s - %(levelname)s - %(message)s',
    datefmt='%Y-%m-%d %H:%M:%S'
)

12. 最佳实践总结

12.1 代码规范

  • 使用类型提示（Type Hints）

  • 所有异步函数使用 async def

  • 使用 Pydantic 模型进行数据验证

  • 遵循 PEP 8 代码风格

12.2 错误处理

  • 使用 HTTPException 抛出标准 HTTP 错误

  • 记录所有异常到日志

  • 返回友好的错误信息

12.3 性能建议

  • 使用异步 I/O 处理文件操作

  • 大文件使用流式传输

  • 合理设置超时时间

  • 使用连接池管理数据库连接

联系方式

  • 微信公众号：DetectionHub

# electron # fastapi # 目标检测 # 人工智能 # 深度学习
Logo
九章云极普惠算力

更多推荐

轻量级语音识别新标杆：SenseVoice-Small ONNX量化模型部署与性能详解

本文介绍了如何在星图GPU平台自动化部署sensevoice-small-语音识别-onnx模型(带量化后)，实现高效的多语言语音转写。该轻量级模型支持实时语音识别、情感分析和音频事件检测，典型应用于会议记录转录、智能客服质检等场景，大幅提升语音处理效率。

avatar 九章云极普惠算力

Qwen3-ForcedAligner-0.6B部署教程：3步完成Qwen3-ASR本地语音识别环境搭建

本文介绍了如何在星图GPU平台自动化部署Qwen3-ForcedAligner-0.6B镜像，快速搭建本地语音识别环境。该镜像支持多语言语音转录和毫秒级时间戳对齐，适用于视频字幕制作、会议记录转写等场景，保障数据隐私与处理效率。

avatar 九章云极普惠算力

EasyAnimateV5-7b-zh-InP镜像免配置方案：预装Magvit+Qwen v5.1开箱即用

本文介绍了如何在星图GPU平台上自动化部署EasyAnimateV5-7b-zh-InP/7B参数量图生视频模型。该预装镜像开箱即用，用户无需复杂配置即可快速将静态图片转化为动态短视频，轻松应用于社交媒体内容制作、产品动态展示等场景。

avatar 九章云极普惠算力